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-2004 Ada Core Technologies, Inc. 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, 59 Temple Place - Suite 330, Boston, o
21 @c MA 02111-1307, USA. o
23 @c oooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooo
25 @setfilename gnat-style.info
27 @settitle GNAT Coding Style
28 @setchapternewpage odd
31 @dircategory Programming
33 * gnat-style: (gnat-style). GNAT Coding Style
36 @macro syntax{element}
43 @title GNAT Coding Style
45 @titlefont{A Guide for GNAT Developers}
48 @subtitle GNAT, The GNU Ada 95 Compiler
50 @author Ada Core Technologies, Inc.
53 @vskip 0pt plus 1filll
55 Copyright @copyright{} 1995-2003, Free Software Foundation
57 Permission is granted to copy, distribute and/or modify this document
58 under the terms of the GNU Free Documentation License, Version 1.1
59 or any later version published by the Free Software Foundation;
60 with the Invariant Sections being ``GNU Free Documentation License'', with the
61 Front-Cover Texts being
62 ``GNAT Coding Style'' and ``A Guide for GNAT Developers'',
63 and with no Back-Cover Texts.
64 A copy of the license is included in the section entitled
65 ``GNU Free Documentation License''.
70 @node Top, General, , (dir)
71 @comment node-name, next, previous, up
76 A Guide for GNAT Developers
79 GNAT, The GNU Ada 95 Compiler@*
82 Permission is granted to copy, distribute and/or modify this document
83 under the terms of the GNU Free Documentation License, Version 1.1
84 or any later version published by the Free Software Foundation;
85 with the Invariant Sections being ``GNU Free Documentation License'', with the
86 Front-Cover Texts being
87 ``GNAT Coding Style'' and ``A Guide for GNAT Developers''
88 and with no Back-Cover Texts.
89 A copy of the license is included in the section entitled
90 ``GNU Free Documentation License''.
97 * Declarations and Types::
98 * Expressions and Names::
102 * Program Structure::
103 * GNU Free Documentation License::
107 @c -------------------------------------------------------------------------
108 @node General, Lexical Elements, Top, Top
110 @c -------------------------------------------------------------------------
113 Most of GNAT is written in Ada using a consistent style to ensure
114 readability of the code. This document has been written to help
115 maintain this consistent style, while having a large group of developers
116 work on the compiler.
118 For the coding style in the C parts of the compiler and run time,
119 see the GNU Coding Guidelines.
121 This document is structured after the @cite{Ada Reference Manual}.
122 Those familiar with that document should be able to quickly
123 lookup style rules for particular constructs.
126 @c -------------------------------------------------------------------------
127 @node Lexical Elements, Declarations and Types, General, Top
128 @section Lexical Elements
129 @c -------------------------------------------------------------------------
130 @cindex Lexical elements
132 @subsection Character Set and Separators
133 @c -------------------------------------------------------------------------
134 @cindex Character set
143 The character set used should be plain 7-bit ASCII@.
144 The only separators allowed are space and the end-of-line sequence.
145 No other control character or format effector (such as @code{HT},
146 @code{VT}, @code{FF})
148 The normal end-of-line sequence is used, which may be
149 @code{LF}, @code{CR/LF} or @code{CR},
150 depending on the host system. An optional @code{SUB}
151 (@code{16#1A#}) may be present as the
152 last character in the file on hosts using that character as file terminator.
155 Files that are checked in or distributed should be in host format.
158 A line should never be longer than 79 characters, not counting the line
162 Lines must not have trailing blanks.
165 Indentation is 3 characters per level for @code{if} statements, loops, and
166 @code{case} statements.
167 For exact information on required spacing between lexical
168 elements, see file @file{style.adb}.
169 @cindex @file{style.adb} file
173 @subsection Identifiers
174 @c -------------------------------------------------------------------------
179 Identifiers will start with an upper case letter, and each letter following
180 an underscore will be upper case.
181 @cindex Casing (for identifiers)
182 Short acronyms may be all upper case.
183 All other letters are lower case.
184 An exception is for identifiers matching a foreign language. In particular,
185 we use all lower case where appropriate for C@.
188 Use underscores to separate words in an identifier.
191 @item Try to limit your use of abbreviations in identifiers.
192 It is ok to make a few abbreviations, explain what they mean, and then
193 use them frequently, but don't use lots of obscure abbreviations. An
194 example is the @code{ALI} word which stands for Ada Library
195 Information and is by convention always written in upper-case when
196 used in entity names.
198 @smallexample @c adanocomment
199 procedure Find_ALI_Files;
203 Don't use the variable name @code{I}, use @code{J} instead; @code{I} is too
204 easily confused with @code{1} in some fonts. Similarly don't use the
205 variable @code{O}, which is too easily mistaken for the number @code{0}.
208 @subsection Numeric Literals
209 @c -------------------------------------------------------------------------
210 @cindex Numeric literals
214 Numeric literals should include underscores where helpful for
221 3.14159_26535_89793_23846
225 @subsection Reserved Words
226 @c -------------------------------------------------------------------------
227 @cindex Reserved words
231 Reserved words use all lower case.
232 @cindex Casing (for reserved words)
234 @smallexample @c adanocomment
239 The words @code{Access}, @code{Delta} and @code{Digits} are
240 capitalized when used as @syntax{attribute_designator}.
244 @c -------------------------------------------------------------------------
249 A comment starts with @code{--} followed by two spaces).
250 The only exception to this rule (i.e.@: one space is tolerated) is when the
251 comment ends with a single space followed by @code{--}.
252 It is also acceptable to have only one space between @code{--} and the start
253 of the comment when the comment is at the end of a line,
257 Every sentence in a comment should start with an upper-case letter (including
258 the first letter of the comment).
259 @cindex Casing (in comments)
262 When declarations are commented with ``hanging'' comments, i.e.@:
263 comments after the declaration, there is no blank line before the
264 comment, and if it is absolutely necessary to have blank lines within
265 the comments these blank lines @emph{do} have a @code{--} (unlike the
266 normal rule, which is to use entirely blank lines for separating
267 comment paragraphs). The comment starts at same level of indentation
268 as code it is commenting.
269 @cindex Blank lines (in comments)
272 @smallexample @c adanocomment
274 -- Integer value for storing value of z
276 -- The previous line was a blank line.
280 Comments that are dubious or incomplete, or that comment on possibly
281 wrong or incomplete code, should be preceded or followed by @code{???}@.
284 Comments in a subprogram body must generally be surrounded by blank lines.
285 An exception is a comment that follows a line containing a single keyword
286 (@code{begin}, @code{else}, @code{loop}):
288 @smallexample @c adanocomment
291 -- Comment for the next statement
295 -- Comment for the B statement
303 In sequences of statements, comments at the end of the lines should be
305 @cindex Alignment (in comments)
307 @smallexample @c adanocomment
308 My_Identifier := 5; -- First comment
309 Other_Id := 6; -- Second comment
313 Short comments that fit on a single line are @emph{not} ended with a
314 period. Comments taking more than a line are punctuated in the normal
318 Comments should focus on @emph{why} instead of @emph{what}.
319 Descriptions of what subprograms do go with the specification.
322 Comments describing a subprogram spec should specifically mention the
323 formal argument names. General rule: write a comment that does not
324 depend on the names of things. The names are supplementary, not
325 sufficient, as comments.
328 @emph{Do not} put two spaces after periods in comments.
331 @c -------------------------------------------------------------------------
332 @node Declarations and Types, Expressions and Names, Lexical Elements,Top
333 @section Declarations and Types
334 @c -------------------------------------------------------------------------
335 @cindex Declarationa and Types
339 In entity declarations, colons must be surrounded by spaces. Colons
341 @cindex Alignment (in declarations)
343 @smallexample @c adanocomment
349 Declarations should be grouped in a logical order.
350 Related groups of declarations may be preceded by a header comment.
353 All local subprograms in a subprogram or package body should be declared
354 before the first local subprogram body.
357 Do not declare local entities that hide global entities.
358 @cindex Hiding of outer entities
361 Do not declare multiple variables in one declaration that spans lines.
362 Start a new declaration on each line, instead.
365 The @syntax{defining_identifier}s of global declarations serve as
366 comments of a sort. So don't choose terse names, but look for names
367 that give useful information instead.
370 Local names can be shorter, because they are used only within
371 one context, where comments explain their purpose.
376 @c -------------------------------------------------------------------------
377 @node Expressions and Names, Statements, Declarations and Types, Top
378 @section Expressions and Names
379 @c -------------------------------------------------------------------------
380 @cindex Expressions and names
385 Every operator must be surrounded by spaces. An exception is that
386 this rule does not apply to the exponentiation operator, for which
387 there are no specific layout rules. The reason for this exception
388 is that sometimes it makes clearer reading to leave out the spaces
389 around exponentiation.
392 @smallexample @c adanocomment
393 E := A * B**2 + 3 * (C - D);
397 Use parentheses where they clarify the intended association of operands
399 @cindex Parenthesization of expressions
400 @smallexample @c adanocomment
405 @c -------------------------------------------------------------------------
406 @node Statements, Subprograms, Expressions and Names, Top
408 @c -------------------------------------------------------------------------
411 @subsection Simple and Compound Statements
412 @c -------------------------------------------------------------------------
413 @cindex Simple and compound statements
417 Use only one statement or label per line.
419 A longer @syntax{sequence_of_statements} may be divided in logical
420 groups or separated from surrounding code using a blank line.
423 @subsection If Statements
424 @c -------------------------------------------------------------------------
425 @cindex @code{if} statement
429 When the @code{if}, @code{elsif} or @code{else} keywords fit on the
430 same line with the condition and the @code{then} keyword, then the
431 statement is formatted as follows:
432 @cindex Alignment (in an @code{if} statement)
434 @smallexample @c adanocomment
436 if @var{condition} then
438 elsif @var{condition} then
447 When the above layout is not possible, @code{then} should be aligned
448 with @code{if}, and conditions should preferably be split before an
449 @code{and} or @code{or} keyword a follows:
451 @smallexample @c adanocomment
453 if @var{long_condition_that_has_to_be_split}
454 and then @var{continued_on_the_next_line}
462 The @code{elsif}, @code{else} and @code{end if} always line up with
463 the @code{if} keyword. The preferred location for splitting the line
464 is before @code{and} or @code{or}. The continuation of a condition is
465 indented with two spaces or as many as needed to make nesting clear.
466 As an exception, if conditions are closely related either of the
467 following is allowed:
471 if x = lakdsjfhlkashfdlkflkdsalkhfsalkdhflkjdsahf
473 x = asldkjhalkdsjfhhfd
482 if x = lakdsjfhlkashfdlkflkdsalkhfsalkdhflkjdsahf or else
483 x = asldkjhalkdsjfhhfd or else
492 Conditions should use short-circuit forms (@code{and then},
493 @code{or else}), except when the operands are boolean variables
494 or boolean constants.
495 @cindex Short-circuit forms
498 Complex conditions in @code{if} statements are indented two characters:
499 @cindex Indentation (in @code{if} statements)
501 @smallexample @c adanocomment
503 if @var{this_complex_condition}
504 and then @var{that_other_one}
505 and then @var{one_last_one}
513 There are some cases where complex conditionals can be laid out
514 in manners that do not follow these rules to preserve better
515 parallelism between branches, e.g.
517 @smallexample @c adanocomment
519 if xyz.abc (gef) = 'c'
530 Every @code{if} block is preceded and followed by a blank line, except
531 where it begins or ends a @syntax{sequence_of_statements}.
532 @cindex Blank lines (in an @code{if} statement)
534 @smallexample @c adanocomment
547 @subsection Case Statements
548 @cindex @code{case} statements
552 Layout is as below. For long @code{case} statements, the extra indentation
553 can be saved by aligning the @code{when} clauses with the opening @code{case}.
555 @smallexample @c adanocomment
557 case @var{expression} is
558 when @var{condition} =>
560 when @var{condition} =>
567 @subsection Loop Statements
568 @cindex Loop statements
572 When possible, have @code{for} or @code{while} on one line with the
573 condition and the @code{loop} keyword.
575 @smallexample @c adanocomment
577 for J in S'Range loop
584 If the condition is too long, split the condition (see ``If
585 statements'' above) and align @code{loop} with the @code{for} or
586 @code{while} keyword.
587 @cindex Alignment (in a loop statement)
589 @smallexample @c adanocomment
591 while @var{long_condition_that_has_to_be_split}
592 and then @var{continued_on_the_next_line}
600 If the @syntax{loop_statement} has an identifier, it is laid out as follows:
602 @smallexample @c adanocomment
604 Outer : while not @var{condition} loop
611 @subsection Block Statements
612 @cindex Block statement
616 The @code{declare} (optional), @code{begin} and @code{end} words
617 are aligned, except when the @syntax{block_statement} is named. There
618 is a blank line before the @code{begin} keyword:
619 @cindex Alignment (in a block statement)
621 @smallexample @c adanocomment
634 @c -------------------------------------------------------------------------
635 @node Subprograms, Packages, Statements, Top
637 @c -------------------------------------------------------------------------
640 @subsection Subprogram Declarations
641 @c -------------------------------------------------------------------------
645 Do not write the @code{in} for parameters, especially in functions:
647 @smallexample @c adanocomment
648 function Length (S : String) return Integer;
652 When the declaration line for a procedure or a function is too long to fit
653 the entire declaration (including the keyword procedure or function) on a
654 single line, then fold it, putting a single parameter on a line, aligning
657 @smallexample @c adanocomment
659 procedure Set_Heading
662 Pad : Character := Space;
663 Fill : Boolean := True);
668 In the case of a function, if the entire spec does not fit on one line, then
669 the return may appear after the last parameter, as in:
671 @smallexample @c adanocomment
676 Pad : Character := Space) return String;
681 Or it may appear on its own as a separate line. This form is preferred when
682 putting the return on the same line as the last parameter would result in
683 an overlong line. The return type may optionally be aligned with the types
684 of the parameters (usually we do this aligning if it results only in a small
685 number of extra spaces, and otherwise we don't attempt to align). So two
686 alternative forms for the above spec are:
688 @smallexample @c adanocomment
693 Pad : Character := Space)
699 Pad : Character := Space)
706 @subsection Subprogram Bodies
707 @c -------------------------------------------------------------------------
708 @cindex Subprogram bodies
712 Function and procedure bodies should usually be sorted alphabetically. Do
713 not attempt to sort them in some logical order by functionality. For a
714 sequence of subrpgroams specs, a general alphabetical sorting is also
715 usually appropriate, but occasionally it makes sense to group by major
716 function, with appropriate headers.
719 All subprograms have a header giving the function name, with the following
722 @smallexample @c adanocomment
728 procedure My_Function is
736 Note that the name in the header is preceded by a single space,
737 not two spaces as for other comments. These headers are used on
738 nested subprograms as well as outer level subprograms. They may
739 also be used as headers for sections of comments, or collections
740 of declarations that are related.
743 Every subprogram body must have a preceding @syntax{subprogram_declaration}.
746 @cindex Blank lines (in subprogram bodies)
747 A sequence of declarations may optionally be separated from the following
748 begin by a blank line. Just as we optionally allow blank lines in general
749 between declarations, this blank line should be present only if it improves
750 readability. Generally we avoid this blank line if the declarative part is
751 small (one or two lines) and we include it if the declarative part is long.
754 If the declarations in a subprogram contain at least one nested
755 subprogram body, then just before the @code{begin} of the enclosing
756 subprogram, there is a comment line and a blank line:
758 @smallexample @c adanocomment
760 -- Start of processing for @var{Enclosing_Subprogram}
764 end @var{Enclosing_Subprogram};
770 @c -------------------------------------------------------------------------
771 @node Packages, Program Structure, Subprograms, Top
772 @section Packages and Visibility Rules
773 @c -------------------------------------------------------------------------
778 All program units and subprograms have their name at the end:
780 @smallexample @c adanocomment
789 We will use the style of @code{use}-ing @code{with}-ed packages, with
790 the context clauses looking like:
791 @cindex @code{use} clauses
793 @smallexample @c adanocomment
801 Names declared in the visible part of packages should be
802 unique, to prevent name clashes when the packages are @code{use}d.
803 @cindex Name clash avoidance
805 @smallexample @c adanocomment
808 type Entity_Kind is ...;
815 After the file header comment, the context clause and unit specification
816 should be the first thing in a @syntax{program_unit}.
819 @c -------------------------------------------------------------------------
820 @node Program Structure, GNU Free Documentation License, Packages, Top
821 @section Program Structure and Compilation Issues
822 @c -------------------------------------------------------------------------
823 @cindex Program structure
827 Every GNAT source file must be compiled with the @option{-gnatg}
828 switch to check the coding style.
829 (Note that you should look at
830 @file{style.adb} to see the lexical rules enforced by
832 @cindex @option{-gnatg} option (to gcc)
833 @cindex @file{style.adb} file
836 Each source file should contain only one compilation unit.
839 Filenames should be 8 or fewer characters, followed by the @code{.adb}
840 extension for a body or @code{.ads} for a spec.
841 @cindex File name length
844 Unit names should be distinct when ``krunch''ed to 8 characters
845 (see @file{krunch.ads}) and the filenames should match the unit name,
846 except that they are all lower case.
847 @cindex @file{krunch.ads} file
851 @c **********************************
852 @c * GNU Free Documentation License *
853 @c **********************************
855 @c GNU Free Documentation License
856 @cindex GNU Free Documentation License
858 @node Index,,GNU Free Documentation License, Top