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 GNAT is maintained by Ada Core Technologies Inc (http://www.gnat.com). o
12 @c oooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooo
14 @setfilename gnat-style.info
17 Copyright @copyright{} 1992-2008, Free Software Foundation, Inc.
19 Permission is granted to copy, distribute and/or modify this document
20 under the terms of the GNU Free Documentation License, Version 1.3 or
21 any later version published by the Free Software Foundation; with no
22 Invariant Sections, with no Front-Cover Texts and with no Back-Cover
23 Texts. A copy of the license is included in the section entitled
24 ``GNU Free Documentation License''.
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 A Guide for GNAT Developers
46 @subtitle GNAT, The GNU Ada Compiler
48 @author Ada Core Technologies, Inc.
50 @vskip 0pt plus 1filll
57 @node Top, General, , (dir)
58 @comment node-name, next, previous, up
63 A Guide for GNAT Developers
66 GNAT, The GNU Ada Compiler@*
76 * Declarations and Types::
77 * Expressions and Names::
82 * GNU Free Documentation License::
86 @c -------------------------------------------------------------------------
87 @node General, Lexical Elements, Top, Top
89 @c -------------------------------------------------------------------------
92 Most of GNAT is written in Ada using a consistent style to ensure
93 readability of the code. This document has been written to help
94 maintain this consistent style, while having a large group of developers
97 For the coding style in the C parts of the compiler and run time,
98 see the GNU Coding Guidelines.
100 This document is structured after the @cite{Ada Reference Manual}.
101 Those familiar with that document should be able to quickly
102 lookup style rules for particular constructs.
105 @c -------------------------------------------------------------------------
106 @node Lexical Elements, Declarations and Types, General, Top
107 @section Lexical Elements
108 @c -------------------------------------------------------------------------
109 @cindex Lexical elements
111 @subsection Character Set and Separators
112 @c -------------------------------------------------------------------------
113 @cindex Character set
122 The character set used should be plain 7-bit ASCII@.
123 The only separators allowed are space and the end-of-line sequence.
124 No other control character or format effector (such as @code{HT},
125 @code{VT}, @code{FF})
127 The normal end-of-line sequence is used, which may be
128 @code{LF}, @code{CR/LF} or @code{CR},
129 depending on the host system. An optional @code{SUB}
130 (@code{16#1A#}) may be present as the
131 last character in the file on hosts using that character as file terminator.
134 Files that are checked in or distributed should be in host format.
137 A line should never be longer than 79 characters, not counting the line
141 Lines must not have trailing blanks.
144 Indentation is 3 characters per level for @code{if} statements, loops, and
145 @code{case} statements.
146 For exact information on required spacing between lexical
147 elements, see file @file{style.adb}.
148 @cindex @file{style.adb} file
152 @subsection Identifiers
153 @c -------------------------------------------------------------------------
158 Identifiers will start with an upper case letter, and each letter following
159 an underscore will be upper case.
160 @cindex Casing (for identifiers)
161 Short acronyms may be all upper case.
162 All other letters are lower case.
163 An exception is for identifiers matching a foreign language. In particular,
164 we use all lower case where appropriate for C@.
167 Use underscores to separate words in an identifier.
170 @item Try to limit your use of abbreviations in identifiers.
171 It is ok to make a few abbreviations, explain what they mean, and then
172 use them frequently, but don't use lots of obscure abbreviations. An
173 example is the @code{ALI} word which stands for Ada Library
174 Information and is by convention always written in upper-case when
175 used in entity names.
177 @smallexample @c adanocomment
178 procedure Find_ALI_Files;
182 Don't use the variable name @code{I}, use @code{J} instead; @code{I} is too
183 easily confused with @code{1} in some fonts. Similarly don't use the
184 variable @code{O}, which is too easily mistaken for the number @code{0}.
187 @subsection Numeric Literals
188 @c -------------------------------------------------------------------------
189 @cindex Numeric literals
193 Numeric literals should include underscores where helpful for
200 3.14159_26535_89793_23846
204 @subsection Reserved Words
205 @c -------------------------------------------------------------------------
206 @cindex Reserved words
210 Reserved words use all lower case.
211 @cindex Casing (for reserved words)
213 @smallexample @c adanocomment
218 The words @code{Access}, @code{Delta} and @code{Digits} are
219 capitalized when used as @syntax{attribute_designator}.
223 @c -------------------------------------------------------------------------
228 A comment starts with @code{--} followed by two spaces.
229 The only exception to this rule (i.e.@: one space is tolerated) is when the
230 comment ends with a single space followed by @code{--}.
231 It is also acceptable to have only one space between @code{--} and the start
232 of the comment when the comment is at the end of a line,
236 Every sentence in a comment should start with an upper-case letter (including
237 the first letter of the comment).
238 @cindex Casing (in comments)
241 When declarations are commented with ``hanging'' comments, i.e.@:
242 comments after the declaration, there is no blank line before the
243 comment, and if it is absolutely necessary to have blank lines within
244 the comments, e.g. to make paragraph separations within a single comment,
245 these blank lines @emph{do} have a @code{--} (unlike the
246 normal rule, which is to use entirely blank lines for separating
247 comment paragraphs). The comment starts at same level of indentation
248 as code it is commenting.
249 @cindex Blank lines (in comments)
252 @smallexample @c adanocomment
254 -- Integer value for storing value of z
256 -- The previous line was a blank line.
260 Comments that are dubious or incomplete, or that comment on possibly
261 wrong or incomplete code, should be preceded or followed by @code{???}@.
264 Comments in a subprogram body must generally be surrounded by blank lines.
265 An exception is a comment that follows a line containing a single keyword
266 (@code{begin}, @code{else}, @code{loop}):
268 @smallexample @c adanocomment
271 -- Comment for the next statement
275 -- Comment for the B statement
283 In sequences of statements, comments at the end of the lines should be
285 @cindex Alignment (in comments)
287 @smallexample @c adanocomment
288 My_Identifier := 5; -- First comment
289 Other_Id := 6; -- Second comment
293 Short comments that fit on a single line are @emph{not} ended with a
294 period. Comments taking more than a line are punctuated in the normal
298 Comments should focus on @emph{why} instead of @emph{what}.
299 Descriptions of what subprograms do go with the specification.
302 Comments describing a subprogram spec should specifically mention the
303 formal argument names. General rule: write a comment that does not
304 depend on the names of things. The names are supplementary, not
305 sufficient, as comments.
308 @emph{Do not} put two spaces after periods in comments.
311 @c -------------------------------------------------------------------------
312 @node Declarations and Types, Expressions and Names, Lexical Elements,Top
313 @section Declarations and Types
314 @c -------------------------------------------------------------------------
315 @cindex Declarations and Types
319 In entity declarations, colons must be surrounded by spaces. Colons
321 @cindex Alignment (in declarations)
323 @smallexample @c adanocomment
329 Declarations should be grouped in a logical order.
330 Related groups of declarations may be preceded by a header comment.
333 All local subprograms in a subprogram or package body should be declared
334 before the first local subprogram body.
337 Do not declare local entities that hide global entities.
338 @cindex Hiding of outer entities
341 Do not declare multiple variables in one declaration that spans lines.
342 Start a new declaration on each line, instead.
345 The @syntax{defining_identifier}s of global declarations serve as
346 comments of a sort. So don't choose terse names, but look for names
347 that give useful information instead.
350 Local names can be shorter, because they are used only within
351 one context, where comments explain their purpose.
356 @c -------------------------------------------------------------------------
357 @node Expressions and Names, Statements, Declarations and Types, Top
358 @section Expressions and Names
359 @c -------------------------------------------------------------------------
360 @cindex Expressions and names
365 Every operator must be surrounded by spaces. An exception is that
366 this rule does not apply to the exponentiation operator, for which
367 there are no specific layout rules. The reason for this exception
368 is that sometimes it makes clearer reading to leave out the spaces
369 around exponentiation.
372 @smallexample @c adanocomment
373 E := A * B**2 + 3 * (C - D);
377 Use parentheses where they clarify the intended association of operands
379 @cindex Parenthesization of expressions
380 @smallexample @c adanocomment
385 @c -------------------------------------------------------------------------
386 @node Statements, Subprograms, Expressions and Names, Top
388 @c -------------------------------------------------------------------------
391 @subsection Simple and Compound Statements
392 @c -------------------------------------------------------------------------
393 @cindex Simple and compound statements
397 Use only one statement or label per line.
399 A longer @syntax{sequence_of_statements} may be divided in logical
400 groups or separated from surrounding code using a blank line.
403 @subsection If Statements
404 @c -------------------------------------------------------------------------
405 @cindex @code{if} statement
409 When the @code{if}, @code{elsif} or @code{else} keywords fit on the
410 same line with the condition and the @code{then} keyword, then the
411 statement is formatted as follows:
412 @cindex Alignment (in an @code{if} statement)
414 @smallexample @c adanocomment
416 if @var{condition} then
418 elsif @var{condition} then
427 When the above layout is not possible, @code{then} should be aligned
428 with @code{if}, and conditions should preferably be split before an
429 @code{and} or @code{or} keyword a follows:
431 @smallexample @c adanocomment
433 if @var{long_condition_that_has_to_be_split}
434 and then @var{continued_on_the_next_line}
442 The @code{elsif}, @code{else} and @code{end if} always line up with
443 the @code{if} keyword. The preferred location for splitting the line
444 is before @code{and} or @code{or}. The continuation of a condition is
445 indented with two spaces or as many as needed to make nesting clear.
446 As an exception, if conditions are closely related either of the
447 following is allowed:
451 if x = lakdsjfhlkashfdlkflkdsalkhfsalkdhflkjdsahf
453 x = asldkjhalkdsjfhhfd
462 if x = lakdsjfhlkashfdlkflkdsalkhfsalkdhflkjdsahf or else
463 x = asldkjhalkdsjfhhfd or else
472 Conditions should use short-circuit forms (@code{and then},
473 @code{or else}), except when the operands are boolean variables
474 or boolean constants.
475 @cindex Short-circuit forms
478 Complex conditions in @code{if} statements are indented two characters:
479 @cindex Indentation (in @code{if} statements)
481 @smallexample @c adanocomment
483 if @var{this_complex_condition}
484 and then @var{that_other_one}
485 and then @var{one_last_one}
493 There are some cases where complex conditionals can be laid out
494 in manners that do not follow these rules to preserve better
495 parallelism between branches, e.g.
497 @smallexample @c adanocomment
499 if xyz.abc (gef) = 'c'
510 Every @code{if} block is preceded and followed by a blank line, except
511 where it begins or ends a @syntax{sequence_of_statements}.
512 @cindex Blank lines (in an @code{if} statement)
514 @smallexample @c adanocomment
527 @subsection Case Statements
528 @cindex @code{case} statements
532 Layout is as below. For long @code{case} statements, the extra indentation
533 can be saved by aligning the @code{when} clauses with the opening @code{case}.
535 @smallexample @c adanocomment
537 case @var{expression} is
538 when @var{condition} =>
540 when @var{condition} =>
547 @subsection Loop Statements
548 @cindex Loop statements
552 When possible, have @code{for} or @code{while} on one line with the
553 condition and the @code{loop} keyword.
555 @smallexample @c adanocomment
557 for J in S'Range loop
564 If the condition is too long, split the condition (see ``If
565 statements'' above) and align @code{loop} with the @code{for} or
566 @code{while} keyword.
567 @cindex Alignment (in a loop statement)
569 @smallexample @c adanocomment
571 while @var{long_condition_that_has_to_be_split}
572 and then @var{continued_on_the_next_line}
580 If the @syntax{loop_statement} has an identifier, it is laid out as follows:
582 @smallexample @c adanocomment
584 Outer : while not @var{condition} loop
591 @subsection Block Statements
592 @cindex Block statement
596 The @code{declare} (optional), @code{begin} and @code{end} words
597 are aligned, except when the @syntax{block_statement} is named. There
598 is a blank line before the @code{begin} keyword:
599 @cindex Alignment (in a block statement)
601 @smallexample @c adanocomment
614 @c -------------------------------------------------------------------------
615 @node Subprograms, Packages, Statements, Top
617 @c -------------------------------------------------------------------------
620 @subsection Subprogram Declarations
621 @c -------------------------------------------------------------------------
625 Do not write the @code{in} for parameters.
627 @smallexample @c adanocomment
628 function Length (S : String) return Integer;
632 When the declaration line for a procedure or a function is too long to fit
633 the entire declaration (including the keyword procedure or function) on a
634 single line, then fold it, putting a single parameter on a line, aligning
637 @smallexample @c adanocomment
639 procedure Set_Heading
642 Pad : Character := Space;
643 Fill : Boolean := True);
648 In the case of a function, if the entire spec does not fit on one line, then
649 the return may appear after the last parameter, as in:
651 @smallexample @c adanocomment
656 Pad : Character := Space) return String;
661 Or it may appear on its own as a separate line. This form is preferred when
662 putting the return on the same line as the last parameter would result in
663 an overlong line. The return type may optionally be aligned with the types
664 of the parameters (usually we do this aligning if it results only in a small
665 number of extra spaces, and otherwise we don't attempt to align). So two
666 alternative forms for the above spec are:
668 @smallexample @c adanocomment
673 Pad : Character := Space)
679 Pad : Character := Space)
686 @subsection Subprogram Bodies
687 @c -------------------------------------------------------------------------
688 @cindex Subprogram bodies
692 Function and procedure bodies should usually be sorted alphabetically. Do
693 not attempt to sort them in some logical order by functionality. For a
694 sequence of subprogram specs, a general alphabetical sorting is also
695 usually appropriate, but occasionally it makes sense to group by major
696 function, with appropriate headers.
699 All subprograms have a header giving the function name, with the following
702 @smallexample @c adanocomment
708 procedure My_Function is
716 Note that the name in the header is preceded by a single space,
717 not two spaces as for other comments. These headers are used on
718 nested subprograms as well as outer level subprograms. They may
719 also be used as headers for sections of comments, or collections
720 of declarations that are related.
723 Every subprogram body must have a preceding @syntax{subprogram_declaration}.
726 @cindex Blank lines (in subprogram bodies)
727 A sequence of declarations may optionally be separated from the following
728 begin by a blank line. Just as we optionally allow blank lines in general
729 between declarations, this blank line should be present only if it improves
730 readability. Generally we avoid this blank line if the declarative part is
731 small (one or two lines) and the body has no blank lines, and we include it
732 if the declarative part is long or if the body has blank lines.
735 If the declarations in a subprogram contain at least one nested
736 subprogram body, then just before the @code{begin} of the enclosing
737 subprogram, there is a comment line and a blank line:
739 @smallexample @c adanocomment
741 -- Start of processing for @var{Enclosing_Subprogram}
745 end @var{Enclosing_Subprogram};
750 When nested subprograms are present, variables that are referenced by any
751 nested subprogram should precede the nested subprogram specs. For variables
752 that are not referenced by nested procedures, the declarations can either also
753 be before any of the nested subprogram specs (this is the old style, more
754 generally used). Or then can come just before the begin, with a header. The
755 following example shows the two possible styles:
757 @smallexample @c adanocomment
760 Var_Referenced_In_Nested : Integer;
761 Var_Referenced_Only_In_Style1 : Integer;
776 -- Start of processing for Style1
786 Var_Referenced_In_Nested : Integer;
802 Var_Referenced_Only_In_Style2 : Integer;
804 -- Start of processing for Style2
814 For new code, we generally prefer Style2, but we do not insist on
815 modifying all legacy occurrences of Style1, which is still much
816 more common in the sources.
821 @c -------------------------------------------------------------------------
822 @node Packages, Program Structure, Subprograms, Top
823 @section Packages and Visibility Rules
824 @c -------------------------------------------------------------------------
829 All program units and subprograms have their name at the end:
831 @smallexample @c adanocomment
840 We will use the style of @code{use}-ing @code{with}-ed packages, with
841 the context clauses looking like:
842 @cindex @code{use} clauses
844 @smallexample @c adanocomment
852 Names declared in the visible part of packages should be
853 unique, to prevent name clashes when the packages are @code{use}d.
854 @cindex Name clash avoidance
856 @smallexample @c adanocomment
859 type Entity_Kind is ...;
866 After the file header comment, the context clause and unit specification
867 should be the first thing in a @syntax{program_unit}.
870 Preelaborate, Pure and Elaborate_Body pragmas should be added right after the
871 package name, indented an extra level and using the parameterless form:
873 @smallexample @c adanocomment
875 package Preelaborate_Package is
878 end Preelaborate_Package;
884 @c -------------------------------------------------------------------------
885 @node Program Structure, GNU Free Documentation License, Packages, Top
886 @section Program Structure and Compilation Issues
887 @c -------------------------------------------------------------------------
888 @cindex Program structure
892 Every GNAT source file must be compiled with the @option{-gnatg}
893 switch to check the coding style.
894 (Note that you should look at
895 @file{style.adb} to see the lexical rules enforced by
897 @cindex @option{-gnatg} option (to gcc)
898 @cindex @file{style.adb} file
901 Each source file should contain only one compilation unit.
904 Filenames should be 8 or fewer characters, followed by the @code{.adb}
905 extension for a body or @code{.ads} for a spec.
906 @cindex File name length
909 Unit names should be distinct when ``krunch''ed to 8 characters
910 (see @file{krunch.ads}) and the filenames should match the unit name,
911 except that they are all lower case.
912 @cindex @file{krunch.ads} file
916 @c **********************************
917 @c * GNU Free Documentation License *
918 @c **********************************
920 @c GNU Free Documentation License
921 @cindex GNU Free Documentation License
923 @node Index,,GNU Free Documentation License, Top