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},
494 @cindex Short-circuit forms
497 Complex conditions in @code{if} statements are indented two characters:
498 @cindex Indentation (in @code{if} statements)
500 @smallexample @c adanocomment
502 if @var{this_complex_condition}
503 and then @var{that_other_one}
504 and then @var{one_last_one}
512 Every @code{if} block is preceded and followed by a blank line, except
513 where it begins or ends a @syntax{sequence_of_statements}.
514 @cindex Blank lines (in an @code{if} statement)
516 @smallexample @c adanocomment
529 @subsection Case Statements
530 @cindex @code{case} statements
534 Layout is as below. For long @code{case} statements, the extra indentation
535 can be saved by aligning the @code{when} clauses with the opening @code{case}.
537 @smallexample @c adanocomment
539 case @var{expression} is
540 when @var{condition} =>
542 when @var{condition} =>
549 @subsection Loop Statements
550 @cindex Loop statements
554 When possible, have @code{for} or @code{while} on one line with the
555 condition and the @code{loop} keyword.
557 @smallexample @c adanocomment
559 for J in S'Range loop
566 If the condition is too long, split the condition (see ``If
567 statements'' above) and align @code{loop} with the @code{for} or
568 @code{while} keyword.
569 @cindex Alignment (in a loop statement)
571 @smallexample @c adanocomment
573 while @var{long_condition_that_has_to_be_split}
574 and then @var{continued_on_the_next_line}
582 If the @syntax{loop_statement} has an identifier, it is laid out as follows:
584 @smallexample @c adanocomment
586 Outer : while not @var{condition} loop
593 @subsection Block Statements
594 @cindex Block statement
598 The @code{declare} (optional), @code{begin} and @code{end} words
599 are aligned, except when the @syntax{block_statement} is named. There
600 is a blank line before the @code{begin} keyword:
601 @cindex Alignment (in a block statement)
603 @smallexample @c adanocomment
616 @c -------------------------------------------------------------------------
617 @node Subprograms, Packages, Statements, Top
619 @c -------------------------------------------------------------------------
622 @subsection Subprogram Declarations
623 @c -------------------------------------------------------------------------
627 Do not write the @code{in} for parameters, especially in functions:
629 @smallexample @c adanocomment
630 function Length (S : String) return Integer;
634 When the declaration line for a procedure or a function is too long to fit
635 the entire declaration (including the keyword procedure or function) on a
636 single line, then fold it, putting a single parameter on a line, aligning
639 @smallexample @c adanocomment
641 procedure Set_Heading
644 Pad : Character := Space;
645 Fill : Boolean := True);
650 In the case of a function, if the entire spec does not fit on one line, then
651 the return may appear after the last parameter, as in:
653 @smallexample @c adanocomment
658 Pad : Character := Space) return String;
663 Or it may appear on its own as a separate line. This form is preferred when
664 putting the return on the same line as the last parameter would result in
665 an overlong line. The return type may optionally be aligned with the types
666 of the parameters (usually we do this aligning if it results only in a small
667 number of extra spaces, and otherwise we don't attempt to align). So two
668 alternative forms for the above spec are:
670 @smallexample @c adanocomment
675 Pad : Character := Space)
681 Pad : Character := Space)
688 @subsection Subprogram Bodies
689 @c -------------------------------------------------------------------------
690 @cindex Subprogram bodies
694 Function and procedure bodies should usually be sorted alphabetically. Do
695 not attempt to sort them in some logical order by functionality. For a
696 sequence of subrpgroams specs, a general alphabetical sorting is also
697 usually appropriate, but occasionally it makes sense to group by major
698 function, with appropriate headers.
701 All subprograms have a header giving the function name, with the following
704 @smallexample @c adanocomment
710 procedure My_Function is
718 Note that the name in the header is preceded by a single space,
719 not two spaces as for other comments.
722 Every subprogram body must have a preceding @syntax{subprogram_declaration}.
725 @cindex Blank lines (in subprogram bodies)
726 A sequence of declarations may optionally be separated from the following
727 begin by a blank line. Just as we optionally allow blank lines in general
728 between declarations, this blank line should be present only if it improves
729 readability. Generally we avoid this blank line if the declarative part is
730 small (one or two lines) and we include it if the declarative part is long.
733 If the declarations in a subprogram contain at least one nested
734 subprogram body, then just before the @code{begin} of the enclosing
735 subprogram, there is a comment line and a blank line:
737 @smallexample @c adanocomment
739 -- Start of processing for @var{Enclosing_Subprogram}
743 end @var{Enclosing_Subprogram};
749 @c -------------------------------------------------------------------------
750 @node Packages, Program Structure, Subprograms, Top
751 @section Packages and Visibility Rules
752 @c -------------------------------------------------------------------------
757 All program units and subprograms have their name at the end:
759 @smallexample @c adanocomment
768 We will use the style of @code{use}-ing @code{with}-ed packages, with
769 the context clauses looking like:
770 @cindex @code{use} clauses
772 @smallexample @c adanocomment
780 Names declared in the visible part of packages should be
781 unique, to prevent name clashes when the packages are @code{use}d.
782 @cindex Name clash avoidance
784 @smallexample @c adanocomment
787 type Entity_Kind is ...;
794 After the file header comment, the context clause and unit specification
795 should be the first thing in a @syntax{program_unit}.
798 @c -------------------------------------------------------------------------
799 @node Program Structure, GNU Free Documentation License, Packages, Top
800 @section Program Structure and Compilation Issues
801 @c -------------------------------------------------------------------------
802 @cindex Program structure
806 Every GNAT source file must be compiled with the @option{-gnatg}
807 switch to check the coding style.
808 (Note that you should look at
809 @file{style.adb} to see the lexical rules enforced by
811 @cindex @option{-gnatg} option (to gcc)
812 @cindex @file{style.adb} file
815 Each source file should contain only one compilation unit.
818 Filenames should be 8 or fewer characters, followed by the @code{.adb}
819 extension for a body or @code{.ads} for a spec.
820 @cindex File name length
823 Unit names should be distinct when ``krunch''ed to 8 characters
824 (see @file{krunch.ads}) and the filenames should match the unit name,
825 except that they are all lower case.
826 @cindex @file{krunch.ads} file
830 @c **********************************
831 @c * GNU Free Documentation License *
832 @c **********************************
834 @c GNU Free Documentation License
835 @cindex GNU Free Documentation License
837 @node Index,,GNU Free Documentation License, Top