1 \input texinfo @c -*-texinfo-*-
4 @c oooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooo
6 @c GNAT DOCUMENTATION o
8 @c G N A T C O D I N G S T Y L E o
10 @c Copyright (C) 1992-2007, AdaCore o
12 @c GNAT is free software; you can redistribute it and/or modify it under o
13 @c terms of the GNU General Public License as published by the Free Soft- o
14 @c ware Foundation; either version 2, or (at your option) any later ver- o
15 @c sion. GNAT is distributed in the hope that it will be useful, but WITH- o
16 @c OUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY o
17 @c or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License o
18 @c for more details. You should have received a copy of the GNU General o
19 @c Public License distributed with GNAT; see file COPYING. If not, write o
20 @c to the Free Software Foundation, 51 Franklin Street, Fifth Floor, o
21 @c Boston, MA 02110-1301, USA. o
23 @c oooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooo
25 @setfilename gnat-style.info
27 @settitle GNAT Coding Style
28 @setchapternewpage odd
30 @include gcc-common.texi
32 @dircategory Software development
34 * gnat-style: (gnat-style). GNAT Coding Style
37 @macro syntax{element}
43 @titlefont{GNAT Coding Style:}
45 @title @hfill A Guide for GNAT Developers
46 @subtitle GNAT, The GNU Ada Compiler
48 @author Ada Core Technologies, Inc.
50 @vskip 0pt plus 1filll
52 Copyright @copyright{} 1995-2007, Free Software Foundation
54 Permission is granted to copy, distribute and/or modify this document
55 under the terms of the GNU Free Documentation License, Version 1.1
56 or any later version published by the Free Software Foundation;
57 with the Invariant Sections being ``GNU Free Documentation License'', with the
58 Front-Cover Texts being
59 ``GNAT Coding Style'' and ``A Guide for GNAT Developers'',
60 and with no Back-Cover Texts.
61 A copy of the license is included in the section entitled
62 ``GNU Free Documentation License''.
67 @node Top, General, , (dir)
68 @comment node-name, next, previous, up
73 A Guide for GNAT Developers
76 GNAT, The GNU Ada Compiler@*
79 Permission is granted to copy, distribute and/or modify this document
80 under the terms of the GNU Free Documentation License, Version 1.1
81 or any later version published by the Free Software Foundation;
82 with the Invariant Sections being ``GNU Free Documentation License'', with the
83 Front-Cover Texts being
84 ``GNAT Coding Style'' and ``A Guide for GNAT Developers''
85 and with no Back-Cover Texts.
86 A copy of the license is included in the section entitled
87 ``GNU Free Documentation License''.
94 * Declarations and Types::
95 * Expressions and Names::
100 * GNU Free Documentation License::
104 @c -------------------------------------------------------------------------
105 @node General, Lexical Elements, Top, Top
107 @c -------------------------------------------------------------------------
110 Most of GNAT is written in Ada using a consistent style to ensure
111 readability of the code. This document has been written to help
112 maintain this consistent style, while having a large group of developers
113 work on the compiler.
115 For the coding style in the C parts of the compiler and run time,
116 see the GNU Coding Guidelines.
118 This document is structured after the @cite{Ada Reference Manual}.
119 Those familiar with that document should be able to quickly
120 lookup style rules for particular constructs.
123 @c -------------------------------------------------------------------------
124 @node Lexical Elements, Declarations and Types, General, Top
125 @section Lexical Elements
126 @c -------------------------------------------------------------------------
127 @cindex Lexical elements
129 @subsection Character Set and Separators
130 @c -------------------------------------------------------------------------
131 @cindex Character set
140 The character set used should be plain 7-bit ASCII@.
141 The only separators allowed are space and the end-of-line sequence.
142 No other control character or format effector (such as @code{HT},
143 @code{VT}, @code{FF})
145 The normal end-of-line sequence is used, which may be
146 @code{LF}, @code{CR/LF} or @code{CR},
147 depending on the host system. An optional @code{SUB}
148 (@code{16#1A#}) may be present as the
149 last character in the file on hosts using that character as file terminator.
152 Files that are checked in or distributed should be in host format.
155 A line should never be longer than 79 characters, not counting the line
159 Lines must not have trailing blanks.
162 Indentation is 3 characters per level for @code{if} statements, loops, and
163 @code{case} statements.
164 For exact information on required spacing between lexical
165 elements, see file @file{style.adb}.
166 @cindex @file{style.adb} file
170 @subsection Identifiers
171 @c -------------------------------------------------------------------------
176 Identifiers will start with an upper case letter, and each letter following
177 an underscore will be upper case.
178 @cindex Casing (for identifiers)
179 Short acronyms may be all upper case.
180 All other letters are lower case.
181 An exception is for identifiers matching a foreign language. In particular,
182 we use all lower case where appropriate for C@.
185 Use underscores to separate words in an identifier.
188 @item Try to limit your use of abbreviations in identifiers.
189 It is ok to make a few abbreviations, explain what they mean, and then
190 use them frequently, but don't use lots of obscure abbreviations. An
191 example is the @code{ALI} word which stands for Ada Library
192 Information and is by convention always written in upper-case when
193 used in entity names.
195 @smallexample @c adanocomment
196 procedure Find_ALI_Files;
200 Don't use the variable name @code{I}, use @code{J} instead; @code{I} is too
201 easily confused with @code{1} in some fonts. Similarly don't use the
202 variable @code{O}, which is too easily mistaken for the number @code{0}.
205 @subsection Numeric Literals
206 @c -------------------------------------------------------------------------
207 @cindex Numeric literals
211 Numeric literals should include underscores where helpful for
218 3.14159_26535_89793_23846
222 @subsection Reserved Words
223 @c -------------------------------------------------------------------------
224 @cindex Reserved words
228 Reserved words use all lower case.
229 @cindex Casing (for reserved words)
231 @smallexample @c adanocomment
236 The words @code{Access}, @code{Delta} and @code{Digits} are
237 capitalized when used as @syntax{attribute_designator}.
241 @c -------------------------------------------------------------------------
246 A comment starts with @code{--} followed by two spaces.
247 The only exception to this rule (i.e.@: one space is tolerated) is when the
248 comment ends with a single space followed by @code{--}.
249 It is also acceptable to have only one space between @code{--} and the start
250 of the comment when the comment is at the end of a line,
254 Every sentence in a comment should start with an upper-case letter (including
255 the first letter of the comment).
256 @cindex Casing (in comments)
259 When declarations are commented with ``hanging'' comments, i.e.@:
260 comments after the declaration, there is no blank line before the
261 comment, and if it is absolutely necessary to have blank lines within
262 the comments, e.g. to make paragraph separations within a single comment,
263 these blank lines @emph{do} have a @code{--} (unlike the
264 normal rule, which is to use entirely blank lines for separating
265 comment paragraphs). The comment starts at same level of indentation
266 as code it is commenting.
267 @cindex Blank lines (in comments)
270 @smallexample @c adanocomment
272 -- Integer value for storing value of z
274 -- The previous line was a blank line.
278 Comments that are dubious or incomplete, or that comment on possibly
279 wrong or incomplete code, should be preceded or followed by @code{???}@.
282 Comments in a subprogram body must generally be surrounded by blank lines.
283 An exception is a comment that follows a line containing a single keyword
284 (@code{begin}, @code{else}, @code{loop}):
286 @smallexample @c adanocomment
289 -- Comment for the next statement
293 -- Comment for the B statement
301 In sequences of statements, comments at the end of the lines should be
303 @cindex Alignment (in comments)
305 @smallexample @c adanocomment
306 My_Identifier := 5; -- First comment
307 Other_Id := 6; -- Second comment
311 Short comments that fit on a single line are @emph{not} ended with a
312 period. Comments taking more than a line are punctuated in the normal
316 Comments should focus on @emph{why} instead of @emph{what}.
317 Descriptions of what subprograms do go with the specification.
320 Comments describing a subprogram spec should specifically mention the
321 formal argument names. General rule: write a comment that does not
322 depend on the names of things. The names are supplementary, not
323 sufficient, as comments.
326 @emph{Do not} put two spaces after periods in comments.
329 @c -------------------------------------------------------------------------
330 @node Declarations and Types, Expressions and Names, Lexical Elements,Top
331 @section Declarations and Types
332 @c -------------------------------------------------------------------------
333 @cindex Declarations and Types
337 In entity declarations, colons must be surrounded by spaces. Colons
339 @cindex Alignment (in declarations)
341 @smallexample @c adanocomment
347 Declarations should be grouped in a logical order.
348 Related groups of declarations may be preceded by a header comment.
351 All local subprograms in a subprogram or package body should be declared
352 before the first local subprogram body.
355 Do not declare local entities that hide global entities.
356 @cindex Hiding of outer entities
359 Do not declare multiple variables in one declaration that spans lines.
360 Start a new declaration on each line, instead.
363 The @syntax{defining_identifier}s of global declarations serve as
364 comments of a sort. So don't choose terse names, but look for names
365 that give useful information instead.
368 Local names can be shorter, because they are used only within
369 one context, where comments explain their purpose.
374 @c -------------------------------------------------------------------------
375 @node Expressions and Names, Statements, Declarations and Types, Top
376 @section Expressions and Names
377 @c -------------------------------------------------------------------------
378 @cindex Expressions and names
383 Every operator must be surrounded by spaces. An exception is that
384 this rule does not apply to the exponentiation operator, for which
385 there are no specific layout rules. The reason for this exception
386 is that sometimes it makes clearer reading to leave out the spaces
387 around exponentiation.
390 @smallexample @c adanocomment
391 E := A * B**2 + 3 * (C - D);
395 Use parentheses where they clarify the intended association of operands
397 @cindex Parenthesization of expressions
398 @smallexample @c adanocomment
403 @c -------------------------------------------------------------------------
404 @node Statements, Subprograms, Expressions and Names, Top
406 @c -------------------------------------------------------------------------
409 @subsection Simple and Compound Statements
410 @c -------------------------------------------------------------------------
411 @cindex Simple and compound statements
415 Use only one statement or label per line.
417 A longer @syntax{sequence_of_statements} may be divided in logical
418 groups or separated from surrounding code using a blank line.
421 @subsection If Statements
422 @c -------------------------------------------------------------------------
423 @cindex @code{if} statement
427 When the @code{if}, @code{elsif} or @code{else} keywords fit on the
428 same line with the condition and the @code{then} keyword, then the
429 statement is formatted as follows:
430 @cindex Alignment (in an @code{if} statement)
432 @smallexample @c adanocomment
434 if @var{condition} then
436 elsif @var{condition} then
445 When the above layout is not possible, @code{then} should be aligned
446 with @code{if}, and conditions should preferably be split before an
447 @code{and} or @code{or} keyword a follows:
449 @smallexample @c adanocomment
451 if @var{long_condition_that_has_to_be_split}
452 and then @var{continued_on_the_next_line}
460 The @code{elsif}, @code{else} and @code{end if} always line up with
461 the @code{if} keyword. The preferred location for splitting the line
462 is before @code{and} or @code{or}. The continuation of a condition is
463 indented with two spaces or as many as needed to make nesting clear.
464 As an exception, if conditions are closely related either of the
465 following is allowed:
469 if x = lakdsjfhlkashfdlkflkdsalkhfsalkdhflkjdsahf
471 x = asldkjhalkdsjfhhfd
480 if x = lakdsjfhlkashfdlkflkdsalkhfsalkdhflkjdsahf or else
481 x = asldkjhalkdsjfhhfd or else
490 Conditions should use short-circuit forms (@code{and then},
491 @code{or else}), except when the operands are boolean variables
492 or boolean constants.
493 @cindex Short-circuit forms
496 Complex conditions in @code{if} statements are indented two characters:
497 @cindex Indentation (in @code{if} statements)
499 @smallexample @c adanocomment
501 if @var{this_complex_condition}
502 and then @var{that_other_one}
503 and then @var{one_last_one}
511 There are some cases where complex conditionals can be laid out
512 in manners that do not follow these rules to preserve better
513 parallelism between branches, e.g.
515 @smallexample @c adanocomment
517 if xyz.abc (gef) = 'c'
528 Every @code{if} block is preceded and followed by a blank line, except
529 where it begins or ends a @syntax{sequence_of_statements}.
530 @cindex Blank lines (in an @code{if} statement)
532 @smallexample @c adanocomment
545 @subsection Case Statements
546 @cindex @code{case} statements
550 Layout is as below. For long @code{case} statements, the extra indentation
551 can be saved by aligning the @code{when} clauses with the opening @code{case}.
553 @smallexample @c adanocomment
555 case @var{expression} is
556 when @var{condition} =>
558 when @var{condition} =>
565 @subsection Loop Statements
566 @cindex Loop statements
570 When possible, have @code{for} or @code{while} on one line with the
571 condition and the @code{loop} keyword.
573 @smallexample @c adanocomment
575 for J in S'Range loop
582 If the condition is too long, split the condition (see ``If
583 statements'' above) and align @code{loop} with the @code{for} or
584 @code{while} keyword.
585 @cindex Alignment (in a loop statement)
587 @smallexample @c adanocomment
589 while @var{long_condition_that_has_to_be_split}
590 and then @var{continued_on_the_next_line}
598 If the @syntax{loop_statement} has an identifier, it is laid out as follows:
600 @smallexample @c adanocomment
602 Outer : while not @var{condition} loop
609 @subsection Block Statements
610 @cindex Block statement
614 The @code{declare} (optional), @code{begin} and @code{end} words
615 are aligned, except when the @syntax{block_statement} is named. There
616 is a blank line before the @code{begin} keyword:
617 @cindex Alignment (in a block statement)
619 @smallexample @c adanocomment
632 @c -------------------------------------------------------------------------
633 @node Subprograms, Packages, Statements, Top
635 @c -------------------------------------------------------------------------
638 @subsection Subprogram Declarations
639 @c -------------------------------------------------------------------------
643 Do not write the @code{in} for parameters.
645 @smallexample @c adanocomment
646 function Length (S : String) return Integer;
650 When the declaration line for a procedure or a function is too long to fit
651 the entire declaration (including the keyword procedure or function) on a
652 single line, then fold it, putting a single parameter on a line, aligning
655 @smallexample @c adanocomment
657 procedure Set_Heading
660 Pad : Character := Space;
661 Fill : Boolean := True);
666 In the case of a function, if the entire spec does not fit on one line, then
667 the return may appear after the last parameter, as in:
669 @smallexample @c adanocomment
674 Pad : Character := Space) return String;
679 Or it may appear on its own as a separate line. This form is preferred when
680 putting the return on the same line as the last parameter would result in
681 an overlong line. The return type may optionally be aligned with the types
682 of the parameters (usually we do this aligning if it results only in a small
683 number of extra spaces, and otherwise we don't attempt to align). So two
684 alternative forms for the above spec are:
686 @smallexample @c adanocomment
691 Pad : Character := Space)
697 Pad : Character := Space)
704 @subsection Subprogram Bodies
705 @c -------------------------------------------------------------------------
706 @cindex Subprogram bodies
710 Function and procedure bodies should usually be sorted alphabetically. Do
711 not attempt to sort them in some logical order by functionality. For a
712 sequence of subprogram specs, a general alphabetical sorting is also
713 usually appropriate, but occasionally it makes sense to group by major
714 function, with appropriate headers.
717 All subprograms have a header giving the function name, with the following
720 @smallexample @c adanocomment
726 procedure My_Function is
734 Note that the name in the header is preceded by a single space,
735 not two spaces as for other comments. These headers are used on
736 nested subprograms as well as outer level subprograms. They may
737 also be used as headers for sections of comments, or collections
738 of declarations that are related.
741 Every subprogram body must have a preceding @syntax{subprogram_declaration}.
744 @cindex Blank lines (in subprogram bodies)
745 A sequence of declarations may optionally be separated from the following
746 begin by a blank line. Just as we optionally allow blank lines in general
747 between declarations, this blank line should be present only if it improves
748 readability. Generally we avoid this blank line if the declarative part is
749 small (one or two lines) and the body has no blank lines, and we include it
750 if the declarative part is long or if the body has blank lines.
753 If the declarations in a subprogram contain at least one nested
754 subprogram body, then just before the @code{begin} of the enclosing
755 subprogram, there is a comment line and a blank line:
757 @smallexample @c adanocomment
759 -- Start of processing for @var{Enclosing_Subprogram}
763 end @var{Enclosing_Subprogram};
768 When nested subprograms are present, variables that are referenced by any
769 nested subprogram should precede the nested subprogram specs. For variables
770 that are not referenced by nested procedures, the declarations can either also
771 be before any of the nested subprogram specs (this is the old style, more
772 generally used). Or then can come just before the begin, with a header. The
773 following example shows the two possible styles:
775 @smallexample @c adanocomment
778 Var_Referenced_In_Nested : Integer;
779 Var_Referenced_Only_In_Style1 : Integer;
794 -- Start of processing for Style1
804 Var_Referenced_In_Nested : Integer;
820 Var_Referenced_Only_In_Style2 : Integer;
822 -- Start of processing for Style2
832 For new code, we generally prefer Style2, but we do not insist on
833 modifying all legacy occurrences of Style1, which is still much
834 more common in the sources.
839 @c -------------------------------------------------------------------------
840 @node Packages, Program Structure, Subprograms, Top
841 @section Packages and Visibility Rules
842 @c -------------------------------------------------------------------------
847 All program units and subprograms have their name at the end:
849 @smallexample @c adanocomment
858 We will use the style of @code{use}-ing @code{with}-ed packages, with
859 the context clauses looking like:
860 @cindex @code{use} clauses
862 @smallexample @c adanocomment
870 Names declared in the visible part of packages should be
871 unique, to prevent name clashes when the packages are @code{use}d.
872 @cindex Name clash avoidance
874 @smallexample @c adanocomment
877 type Entity_Kind is ...;
884 After the file header comment, the context clause and unit specification
885 should be the first thing in a @syntax{program_unit}.
888 Preelaborate, Pure and Elaborate_Body pragmas should be added right after the
889 package name, indented an extra level and using the parameterless form:
891 @smallexample @c adanocomment
893 package Preelaborate_Package is
896 end Preelaborate_Package;
902 @c -------------------------------------------------------------------------
903 @node Program Structure, GNU Free Documentation License, Packages, Top
904 @section Program Structure and Compilation Issues
905 @c -------------------------------------------------------------------------
906 @cindex Program structure
910 Every GNAT source file must be compiled with the @option{-gnatg}
911 switch to check the coding style.
912 (Note that you should look at
913 @file{style.adb} to see the lexical rules enforced by
915 @cindex @option{-gnatg} option (to gcc)
916 @cindex @file{style.adb} file
919 Each source file should contain only one compilation unit.
922 Filenames should be 8 or fewer characters, followed by the @code{.adb}
923 extension for a body or @code{.ads} for a spec.
924 @cindex File name length
927 Unit names should be distinct when ``krunch''ed to 8 characters
928 (see @file{krunch.ads}) and the filenames should match the unit name,
929 except that they are all lower case.
930 @cindex @file{krunch.ads} file
934 @c **********************************
935 @c * GNU Free Documentation License *
936 @c **********************************
938 @c GNU Free Documentation License
939 @cindex GNU Free Documentation License
941 @node Index,,GNU Free Documentation License, Top