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-2005, 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
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-2005, 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, e.g. to make paragraph separations within a single comment,
266 these blank lines @emph{do} have a @code{--} (unlike the
267 normal rule, which is to use entirely blank lines for separating
268 comment paragraphs). The comment starts at same level of indentation
269 as code it is commenting.
270 @cindex Blank lines (in comments)
273 @smallexample @c adanocomment
275 -- Integer value for storing value of z
277 -- The previous line was a blank line.
281 Comments that are dubious or incomplete, or that comment on possibly
282 wrong or incomplete code, should be preceded or followed by @code{???}@.
285 Comments in a subprogram body must generally be surrounded by blank lines.
286 An exception is a comment that follows a line containing a single keyword
287 (@code{begin}, @code{else}, @code{loop}):
289 @smallexample @c adanocomment
292 -- Comment for the next statement
296 -- Comment for the B statement
304 In sequences of statements, comments at the end of the lines should be
306 @cindex Alignment (in comments)
308 @smallexample @c adanocomment
309 My_Identifier := 5; -- First comment
310 Other_Id := 6; -- Second comment
314 Short comments that fit on a single line are @emph{not} ended with a
315 period. Comments taking more than a line are punctuated in the normal
319 Comments should focus on @emph{why} instead of @emph{what}.
320 Descriptions of what subprograms do go with the specification.
323 Comments describing a subprogram spec should specifically mention the
324 formal argument names. General rule: write a comment that does not
325 depend on the names of things. The names are supplementary, not
326 sufficient, as comments.
329 @emph{Do not} put two spaces after periods in comments.
332 @c -------------------------------------------------------------------------
333 @node Declarations and Types, Expressions and Names, Lexical Elements,Top
334 @section Declarations and Types
335 @c -------------------------------------------------------------------------
336 @cindex Declarations and Types
340 In entity declarations, colons must be surrounded by spaces. Colons
342 @cindex Alignment (in declarations)
344 @smallexample @c adanocomment
350 Declarations should be grouped in a logical order.
351 Related groups of declarations may be preceded by a header comment.
354 All local subprograms in a subprogram or package body should be declared
355 before the first local subprogram body.
358 Do not declare local entities that hide global entities.
359 @cindex Hiding of outer entities
362 Do not declare multiple variables in one declaration that spans lines.
363 Start a new declaration on each line, instead.
366 The @syntax{defining_identifier}s of global declarations serve as
367 comments of a sort. So don't choose terse names, but look for names
368 that give useful information instead.
371 Local names can be shorter, because they are used only within
372 one context, where comments explain their purpose.
377 @c -------------------------------------------------------------------------
378 @node Expressions and Names, Statements, Declarations and Types, Top
379 @section Expressions and Names
380 @c -------------------------------------------------------------------------
381 @cindex Expressions and names
386 Every operator must be surrounded by spaces. An exception is that
387 this rule does not apply to the exponentiation operator, for which
388 there are no specific layout rules. The reason for this exception
389 is that sometimes it makes clearer reading to leave out the spaces
390 around exponentiation.
393 @smallexample @c adanocomment
394 E := A * B**2 + 3 * (C - D);
398 Use parentheses where they clarify the intended association of operands
400 @cindex Parenthesization of expressions
401 @smallexample @c adanocomment
406 @c -------------------------------------------------------------------------
407 @node Statements, Subprograms, Expressions and Names, Top
409 @c -------------------------------------------------------------------------
412 @subsection Simple and Compound Statements
413 @c -------------------------------------------------------------------------
414 @cindex Simple and compound statements
418 Use only one statement or label per line.
420 A longer @syntax{sequence_of_statements} may be divided in logical
421 groups or separated from surrounding code using a blank line.
424 @subsection If Statements
425 @c -------------------------------------------------------------------------
426 @cindex @code{if} statement
430 When the @code{if}, @code{elsif} or @code{else} keywords fit on the
431 same line with the condition and the @code{then} keyword, then the
432 statement is formatted as follows:
433 @cindex Alignment (in an @code{if} statement)
435 @smallexample @c adanocomment
437 if @var{condition} then
439 elsif @var{condition} then
448 When the above layout is not possible, @code{then} should be aligned
449 with @code{if}, and conditions should preferably be split before an
450 @code{and} or @code{or} keyword a follows:
452 @smallexample @c adanocomment
454 if @var{long_condition_that_has_to_be_split}
455 and then @var{continued_on_the_next_line}
463 The @code{elsif}, @code{else} and @code{end if} always line up with
464 the @code{if} keyword. The preferred location for splitting the line
465 is before @code{and} or @code{or}. The continuation of a condition is
466 indented with two spaces or as many as needed to make nesting clear.
467 As an exception, if conditions are closely related either of the
468 following is allowed:
472 if x = lakdsjfhlkashfdlkflkdsalkhfsalkdhflkjdsahf
474 x = asldkjhalkdsjfhhfd
483 if x = lakdsjfhlkashfdlkflkdsalkhfsalkdhflkjdsahf or else
484 x = asldkjhalkdsjfhhfd or else
493 Conditions should use short-circuit forms (@code{and then},
494 @code{or else}), except when the operands are boolean variables
495 or boolean constants.
496 @cindex Short-circuit forms
499 Complex conditions in @code{if} statements are indented two characters:
500 @cindex Indentation (in @code{if} statements)
502 @smallexample @c adanocomment
504 if @var{this_complex_condition}
505 and then @var{that_other_one}
506 and then @var{one_last_one}
514 There are some cases where complex conditionals can be laid out
515 in manners that do not follow these rules to preserve better
516 parallelism between branches, e.g.
518 @smallexample @c adanocomment
520 if xyz.abc (gef) = 'c'
531 Every @code{if} block is preceded and followed by a blank line, except
532 where it begins or ends a @syntax{sequence_of_statements}.
533 @cindex Blank lines (in an @code{if} statement)
535 @smallexample @c adanocomment
548 @subsection Case Statements
549 @cindex @code{case} statements
553 Layout is as below. For long @code{case} statements, the extra indentation
554 can be saved by aligning the @code{when} clauses with the opening @code{case}.
556 @smallexample @c adanocomment
558 case @var{expression} is
559 when @var{condition} =>
561 when @var{condition} =>
568 @subsection Loop Statements
569 @cindex Loop statements
573 When possible, have @code{for} or @code{while} on one line with the
574 condition and the @code{loop} keyword.
576 @smallexample @c adanocomment
578 for J in S'Range loop
585 If the condition is too long, split the condition (see ``If
586 statements'' above) and align @code{loop} with the @code{for} or
587 @code{while} keyword.
588 @cindex Alignment (in a loop statement)
590 @smallexample @c adanocomment
592 while @var{long_condition_that_has_to_be_split}
593 and then @var{continued_on_the_next_line}
601 If the @syntax{loop_statement} has an identifier, it is laid out as follows:
603 @smallexample @c adanocomment
605 Outer : while not @var{condition} loop
612 @subsection Block Statements
613 @cindex Block statement
617 The @code{declare} (optional), @code{begin} and @code{end} words
618 are aligned, except when the @syntax{block_statement} is named. There
619 is a blank line before the @code{begin} keyword:
620 @cindex Alignment (in a block statement)
622 @smallexample @c adanocomment
635 @c -------------------------------------------------------------------------
636 @node Subprograms, Packages, Statements, Top
638 @c -------------------------------------------------------------------------
641 @subsection Subprogram Declarations
642 @c -------------------------------------------------------------------------
646 Do not write the @code{in} for parameters, especially in functions:
648 @smallexample @c adanocomment
649 function Length (S : String) return Integer;
653 When the declaration line for a procedure or a function is too long to fit
654 the entire declaration (including the keyword procedure or function) on a
655 single line, then fold it, putting a single parameter on a line, aligning
658 @smallexample @c adanocomment
660 procedure Set_Heading
663 Pad : Character := Space;
664 Fill : Boolean := True);
669 In the case of a function, if the entire spec does not fit on one line, then
670 the return may appear after the last parameter, as in:
672 @smallexample @c adanocomment
677 Pad : Character := Space) return String;
682 Or it may appear on its own as a separate line. This form is preferred when
683 putting the return on the same line as the last parameter would result in
684 an overlong line. The return type may optionally be aligned with the types
685 of the parameters (usually we do this aligning if it results only in a small
686 number of extra spaces, and otherwise we don't attempt to align). So two
687 alternative forms for the above spec are:
689 @smallexample @c adanocomment
694 Pad : Character := Space)
700 Pad : Character := Space)
707 @subsection Subprogram Bodies
708 @c -------------------------------------------------------------------------
709 @cindex Subprogram bodies
713 Function and procedure bodies should usually be sorted alphabetically. Do
714 not attempt to sort them in some logical order by functionality. For a
715 sequence of subrpgroams specs, a general alphabetical sorting is also
716 usually appropriate, but occasionally it makes sense to group by major
717 function, with appropriate headers.
720 All subprograms have a header giving the function name, with the following
723 @smallexample @c adanocomment
729 procedure My_Function is
737 Note that the name in the header is preceded by a single space,
738 not two spaces as for other comments. These headers are used on
739 nested subprograms as well as outer level subprograms. They may
740 also be used as headers for sections of comments, or collections
741 of declarations that are related.
744 Every subprogram body must have a preceding @syntax{subprogram_declaration}.
747 @cindex Blank lines (in subprogram bodies)
748 A sequence of declarations may optionally be separated from the following
749 begin by a blank line. Just as we optionally allow blank lines in general
750 between declarations, this blank line should be present only if it improves
751 readability. Generally we avoid this blank line if the declarative part is
752 small (one or two lines) and we include it if the declarative part is long.
755 If the declarations in a subprogram contain at least one nested
756 subprogram body, then just before the @code{begin} of the enclosing
757 subprogram, there is a comment line and a blank line:
759 @smallexample @c adanocomment
761 -- Start of processing for @var{Enclosing_Subprogram}
765 end @var{Enclosing_Subprogram};
771 @c -------------------------------------------------------------------------
772 @node Packages, Program Structure, Subprograms, Top
773 @section Packages and Visibility Rules
774 @c -------------------------------------------------------------------------
779 All program units and subprograms have their name at the end:
781 @smallexample @c adanocomment
790 We will use the style of @code{use}-ing @code{with}-ed packages, with
791 the context clauses looking like:
792 @cindex @code{use} clauses
794 @smallexample @c adanocomment
802 Names declared in the visible part of packages should be
803 unique, to prevent name clashes when the packages are @code{use}d.
804 @cindex Name clash avoidance
806 @smallexample @c adanocomment
809 type Entity_Kind is ...;
816 After the file header comment, the context clause and unit specification
817 should be the first thing in a @syntax{program_unit}.
820 Preelaborate, Pure and Elaborate_Body pragmas should be added right after the
821 package name, indented an extra level and using the parameterless form:
823 @smallexample @c adanocomment
825 package Preelaborate_Package is
828 end Preelaborate_Package;
834 @c -------------------------------------------------------------------------
835 @node Program Structure, GNU Free Documentation License, Packages, Top
836 @section Program Structure and Compilation Issues
837 @c -------------------------------------------------------------------------
838 @cindex Program structure
842 Every GNAT source file must be compiled with the @option{-gnatg}
843 switch to check the coding style.
844 (Note that you should look at
845 @file{style.adb} to see the lexical rules enforced by
847 @cindex @option{-gnatg} option (to gcc)
848 @cindex @file{style.adb} file
851 Each source file should contain only one compilation unit.
854 Filenames should be 8 or fewer characters, followed by the @code{.adb}
855 extension for a body or @code{.ads} for a spec.
856 @cindex File name length
859 Unit names should be distinct when ``krunch''ed to 8 characters
860 (see @file{krunch.ads}) and the filenames should match the unit name,
861 except that they are all lower case.
862 @cindex @file{krunch.ads} file
866 @c **********************************
867 @c * GNU Free Documentation License *
868 @c **********************************
870 @c GNU Free Documentation License
871 @cindex GNU Free Documentation License
873 @node Index,,GNU Free Documentation License, Top