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-2003 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
49 @subtitle Document revision level $Revision: 1.8 $
50 @subtitle Date: $Date: 2003/05/24 21:29:30 $
52 @author Ada Core Technologies, Inc.
55 @vskip 0pt plus 1filll
57 Copyright @copyright{} 1995-2003, Free Software Foundation
59 Permission is granted to copy, distribute and/or modify this document
60 under the terms of the GNU Free Documentation License, Version 1.1
61 or any later version published by the Free Software Foundation;
62 with the Invariant Sections being ``GNU Free Documentation License'', with the
63 Front-Cover Texts being
64 ``GNAT Coding Style'' and ``A Guide for GNAT Developers'',
65 and with no Back-Cover Texts.
66 A copy of the license is included in the section entitled
67 ``GNU Free Documentation License''.
72 @node Top, General, , (dir)
73 @comment node-name, next, previous, up
78 A Guide for GNAT Developers
81 GNAT, The GNU Ada 95 Compiler@*
82 Document revision level $Revision: 1.8 $@*
83 Date: $Date: 2003/05/24 21:29:30 $
86 Permission is granted to copy, distribute and/or modify this document
87 under the terms of the GNU Free Documentation License, Version 1.1
88 or any later version published by the Free Software Foundation;
89 with the Invariant Sections being ``GNU Free Documentation License'', with the
90 Front-Cover Texts being
91 ``GNAT Coding Style'' and ``A Guide for GNAT Developers''
92 and with no Back-Cover Texts.
93 A copy of the license is included in the section entitled
94 ``GNU Free Documentation License''.
101 * Declarations and Types::
102 * Expressions and Names::
106 * Program Structure::
107 * GNU Free Documentation License::
111 @c -------------------------------------------------------------------------
112 @node General, Lexical Elements, Top, Top
114 @c -------------------------------------------------------------------------
117 Most of GNAT is written in Ada using a consistent style to ensure
118 readability of the code. This document has been written to help
119 maintain this consistent style, while having a large group of developers
120 work on the compiler.
122 For the coding style in the C parts of the compiler and run time,
123 see the GNU Coding Guidelines.
125 This document is structured after the @cite{Ada Reference Manual}.
126 Those familiar with that document should be able to quickly
127 lookup style rules for particular constructs.
130 @c -------------------------------------------------------------------------
131 @node Lexical Elements, Declarations and Types, General, Top
132 @section Lexical Elements
133 @c -------------------------------------------------------------------------
134 @cindex Lexical elements
136 @subsection Character Set and Separators
137 @c -------------------------------------------------------------------------
138 @cindex Character set
147 The character set used should be plain 7-bit ASCII@.
148 The only separators allowed are space and the end-of-line sequence.
149 No other control character or format effector (such as @code{HT},
150 @code{VT}, @code{FF})
152 The normal end-of-line sequence is used, which may be
153 @code{LF}, @code{CR/LF} or @code{CR},
154 depending on the host system. An optional @code{SUB}
155 (@code{16#1A#}) may be present as the
156 last character in the file on hosts using that character as file terminator.
159 Files that are checked in or distributed should be in host format.
162 A line should never be longer than 79 characters, not counting the line
166 Lines must not have trailing blanks.
169 Indentation is 3 characters per level for @code{if} statements, loops, and
170 @code{case} statements.
171 For exact information on required spacing between lexical
172 elements, see file @file{style.adb}.
173 @cindex @file{style.adb} file
177 @subsection Identifiers
178 @c -------------------------------------------------------------------------
183 Identifiers will start with an upper case letter, and each letter following
184 an underscore will be upper case.
185 @cindex Casing (for identifiers)
186 Short acronyms may be all upper case.
187 All other letters are lower case.
188 An exception is for identifiers matching a foreign language. In particular,
189 we use all lower case where appropriate for C@.
192 Use underscores to separate words in an identifier.
195 @item Try to limit your use of abbreviations in identifiers.
196 It is ok to make a few abbreviations, explain what they mean, and then
197 use them frequently, but don't use lots of obscure abbreviations. An
198 example is the @code{ALI} word which stands for Ada Library
199 Information and is by convention always written in upper-case when
200 used in entity names.
202 @smallexample @c adanocomment
203 procedure Find_ALI_Files;
207 Don't use the variable name @code{I}, use @code{J} instead; @code{I} is too
208 easily confused with @code{1} in some fonts. Similarly don't use the
209 variable @code{O}, which is too easily mistaken for the number @code{0}.
212 @subsection Numeric Literals
213 @c -------------------------------------------------------------------------
214 @cindex Numeric literals
218 Numeric literals should include underscores where helpful for
225 3.14159_26535_89793_23846
229 @subsection Reserved Words
230 @c -------------------------------------------------------------------------
231 @cindex Reserved words
235 Reserved words use all lower case.
236 @cindex Casing (for reserved words)
238 @smallexample @c adanocomment
243 The words @code{Access}, @code{Delta} and @code{Digits} are
244 capitalized when used as @syntax{attribute_designator}.
248 @c -------------------------------------------------------------------------
253 A comment starts with @code{--} followed by two spaces).
254 The only exception to this rule (i.e.@: one space is tolerated) is when the
255 comment ends with a single space followed by @code{--}.
256 It is also acceptable to have only one space between @code{--} and the start
257 of the comment when the comment is at the end of a line,
261 Every sentence in a comment should start with an upper-case letter (including
262 the first letter of the comment).
263 @cindex Casing (in comments)
266 When declarations are commented with ``hanging'' comments, i.e.@:
267 comments after the declaration, there is no blank line before the
268 comment, and if it is absolutely necessary to have blank lines within
269 the comments these blank lines @emph{do} have a @code{--} (unlike the
270 normal rule, which is to use entirely blank lines for separating
271 comment paragraphs). The comment starts at same level of indentation
272 as code it is commenting.
273 @cindex Blank lines (in comments)
276 @smallexample @c adanocomment
278 -- Integer value for storing value of z
280 -- The previous line was a blank line.
284 Comments that are dubious or incomplete, or that comment on possibly
285 wrong or incomplete code, should be preceded or followed by @code{???}@.
288 Comments in a subprogram body must generally be surrounded by blank lines.
289 An exception is a comment that follows a line containing a single keyword
290 (@code{begin}, @code{else}, @code{loop}):
292 @smallexample @c adanocomment
295 -- Comment for the next statement
299 -- Comment for the B statement
307 In sequences of statements, comments at the end of the lines should be
309 @cindex Alignment (in comments)
311 @smallexample @c adanocomment
312 My_Identifier := 5; -- First comment
313 Other_Id := 6; -- Second comment
317 Short comments that fit on a single line are @emph{not} ended with a
318 period. Comments taking more than a line are punctuated in the normal
322 Comments should focus on @emph{why} instead of @emph{what}.
323 Descriptions of what subprograms do go with the specification.
326 Comments describing a subprogram spec should specifically mention the
327 formal argument names. General rule: write a comment that does not
328 depend on the names of things. The names are supplementary, not
329 sufficient, as comments.
332 @emph{Do not} put two spaces after periods in comments.
335 @c -------------------------------------------------------------------------
336 @node Declarations and Types, Expressions and Names, Lexical Elements,Top
337 @section Declarations and Types
338 @c -------------------------------------------------------------------------
339 @cindex Declarationa and Types
343 In entity declarations, colons must be surrounded by spaces. Colons
345 @cindex Alignment (in declarations)
347 @smallexample @c adanocomment
353 Declarations should be grouped in a logical order.
354 Related groups of declarations may be preceded by a header comment.
357 All local subprograms in a subprogram or package body should be declared
358 before the first local subprogram body.
361 Do not declare local entities that hide global entities.
362 @cindex Hiding of outer entities
365 Do not declare multiple variables in one declaration that spans lines.
366 Start a new declaration on each line, instead.
369 The @syntax{defining_identifier}s of global declarations serve as
370 comments of a sort. So don't choose terse names, but look for names
371 that give useful information instead.
374 Local names can be shorter, because they are used only within
375 one context, where comments explain their purpose.
380 @c -------------------------------------------------------------------------
381 @node Expressions and Names, Statements, Declarations and Types, Top
382 @section Expressions and Names
383 @c -------------------------------------------------------------------------
384 @cindex Expressions and names
389 Every operator must be surrounded by spaces, except for the
390 exponentiation operator.
393 @smallexample @c adanocomment
394 E := A * B**2 + 3 * (C - D);
398 When folding a long line, fold before an operator, not after.
401 Use parentheses where they clarify the intended association of operands
403 @cindex Parenthesization of expressions
404 @smallexample @c adanocomment
409 @c -------------------------------------------------------------------------
410 @node Statements, Subprograms, Expressions and Names, Top
412 @c -------------------------------------------------------------------------
415 @subsection Simple and Compound Statements
416 @c -------------------------------------------------------------------------
417 @cindex Simple and compound statements
421 Use only one statement or label per line.
423 A longer @syntax{sequence_of_statements} may be divided in logical
424 groups or separated from surrounding code using a blank line.
427 @subsection If Statements
428 @c -------------------------------------------------------------------------
429 @cindex @code{if} statement
433 When the @code{if}, @code{elsif} or @code{else} keywords fit on the
434 same line with the condition and the @code{then} keyword, then the
435 statement is formatted as follows:
436 @cindex Alignment (in an @code{if} statement)
438 @smallexample @c adanocomment
440 if @var{condition} then
442 elsif @var{condition} then
451 When the above layout is not possible, @code{then} should be aligned
452 with @code{if}, and conditions should preferably be split before an
453 @code{and} or @code{or} keyword a follows:
455 @smallexample @c adanocomment
457 if @var{long_condition_that_has_to_be_split}
458 and then @var{continued_on_the_next_line}
466 The @code{elsif}, @code{else} and @code{end if} always line up with
467 the @code{if} keyword. The preferred location for splitting the line
468 is before @code{and} or @code{or}. The continuation of a condition is
469 indented with two spaces or as many as needed to make nesting clear.
470 As an exception, if conditions are closely related either of the
471 following is allowed:
475 if x = lakdsjfhlkashfdlkflkdsalkhfsalkdhflkjdsahf
477 x = asldkjhalkdsjfhhfd
486 if x = lakdsjfhlkashfdlkflkdsalkhfsalkdhflkjdsahf or else
487 x = asldkjhalkdsjfhhfd or else
496 Conditions should use short-circuit forms (@code{and then},
498 @cindex Short-circuit forms
501 Complex conditions in @code{if} statements are indented two characters:
502 @cindex Indentation (in @code{if} statements)
504 @smallexample @c adanocomment
506 if @var{this_complex_condition}
507 and then @var{that_other_one}
508 and then @var{one_last_one}
516 Every @code{if} block is preceded and followed by a blank line, except
517 where it begins or ends a @syntax{sequence_of_statements}.
518 @cindex Blank lines (in an @code{if} statement)
520 @smallexample @c adanocomment
533 @subsection Case Statements
534 @cindex @code{case} statements
538 Layout is as below. For long @code{case} statements, the extra indentation
539 can be saved by aligning the @code{when} clauses with the opening @code{case}.
541 @smallexample @c adanocomment
543 case @var{expression} is
544 when @var{condition} =>
546 when @var{condition} =>
553 @subsection Loop Statements
554 @cindex Loop statements
558 When possible, have @code{for} or @code{while} on one line with the
559 condition and the @code{loop} keyword.
561 @smallexample @c adanocomment
563 for J in S'Range loop
570 If the condition is too long, split the condition (see ``If
571 statements'' above) and align @code{loop} with the @code{for} or
572 @code{while} keyword.
573 @cindex Alignment (in a loop statement)
575 @smallexample @c adanocomment
577 while @var{long_condition_that_has_to_be_split}
578 and then @var{continued_on_the_next_line}
586 If the @syntax{loop_statement} has an identifier, it is laid out as follows:
588 @smallexample @c adanocomment
590 Outer : while not @var{condition} loop
597 @subsection Block Statements
598 @cindex Block statement
602 The @code{declare} (optional), @code{begin} and @code{end} words
603 are aligned, except when the @syntax{block_statement} is named. There
604 is a blank line before the @code{begin} keyword:
605 @cindex Alignment (in a block statement)
607 @smallexample @c adanocomment
620 @c -------------------------------------------------------------------------
621 @node Subprograms, Packages, Statements, Top
623 @c -------------------------------------------------------------------------
626 @subsection Subprogram Declarations
627 @c -------------------------------------------------------------------------
631 Do not write the @code{in} for parameters, especially in functions:
633 @smallexample @c adanocomment
634 function Length (S : String) return Integer;
638 When the declaration line for a procedure or a function is too long to fit
639 the entire declaration (including the keyword procedure or function) on a
640 single line, then fold it, putting a single parameter on a line, aligning
643 @smallexample @c adanocomment
645 procedure Set_Heading
648 Pad : Character := Space;
649 Fill : Boolean := True);
654 In the case of a function, if the entire spec does not fit on one line, then
655 the return may appear after the last parameter, as in:
657 @smallexample @c adanocomment
662 Pad : Character := Space) return String;
667 Or it may appear on its own as a separate line. This form is preferred when
668 putting the return on the same line as the last parameter would result in
669 an overlong line. The return type may optionally be aligned with the types
670 of the parameters (usually we do this aligning if it results only in a small
671 number of extra spaces, and otherwise we don't attempt to align). So two
672 alternative forms for the above spec are:
674 @smallexample @c adanocomment
679 Pad : Character := Space)
685 Pad : Character := Space)
692 @subsection Subprogram Bodies
693 @c -------------------------------------------------------------------------
694 @cindex Subprogram bodies
698 Function and procedure bodies should usually be sorted alphabetically. Do
699 not attempt to sort them in some logical order by functionality. For a
700 sequence of subrpgroams specs, a general alphabetical sorting is also
701 usually appropriate, but occasionally it makes sense to group by major
702 function, with appropriate headers.
705 All subprograms have a header giving the function name, with the following
708 @smallexample @c adanocomment
714 procedure My_Function is
722 Note that the name in the header is preceded by a single space,
723 not two spaces as for other comments.
726 Every subprogram body must have a preceding @syntax{subprogram_declaration}.
729 @cindex Blank lines (in subprogram bodies)
730 A sequence of declarations may optionally be separated from the following
731 begin by a blank line. Just as we optionally allow blank lines in general
732 between declarations, this blank line should be present only if it improves
733 readability. Generally we avoid this blank line if the declarative part is
734 small (one or two lines) and we include it if the declarative part is long.
737 If the declarations in a subprogram contain at least one nested
738 subprogram body, then just before the @code{begin} of the enclosing
739 subprogram, there is a comment line and a blank line:
741 @smallexample @c adanocomment
743 -- Start of processing for @var{Enclosing_Subprogram}
747 end @var{Enclosing_Subprogram};
753 @c -------------------------------------------------------------------------
754 @node Packages, Program Structure, Subprograms, Top
755 @section Packages and Visibility Rules
756 @c -------------------------------------------------------------------------
761 All program units and subprograms have their name at the end:
763 @smallexample @c adanocomment
772 We will use the style of @code{use}-ing @code{with}-ed packages, with
773 the context clauses looking like:
774 @cindex @code{use} clauses
776 @smallexample @c adanocomment
784 Names declared in the visible part of packages should be
785 unique, to prevent name clashes when the packages are @code{use}d.
786 @cindex Name clash avoidance
788 @smallexample @c adanocomment
791 type Entity_Kind is ...;
798 After the file header comment, the context clause and unit specification
799 should be the first thing in a @syntax{program_unit}.
802 @c -------------------------------------------------------------------------
803 @node Program Structure, GNU Free Documentation License, Packages, Top
804 @section Program Structure and Compilation Issues
805 @c -------------------------------------------------------------------------
806 @cindex Program structure
810 Every GNAT source file must be compiled with the @option{-gnatg}
811 switch to check the coding style.
812 (Note that you should look at
813 @file{style.adb} to see the lexical rules enforced by
815 @cindex @option{-gnatg} option (to gcc)
816 @cindex @file{style.adb} file
819 Each source file should contain only one compilation unit.
822 Filenames should be 8 or fewer characters, followed by the @code{.adb}
823 extension for a body or @code{.ads} for a spec.
824 @cindex File name length
827 Unit names should be distinct when ``krunch''ed to 8 characters
828 (see @file{krunch.ads}) and the filenames should match the unit name,
829 except that they are all lower case.
830 @cindex @file{krunch.ads} file
834 @c **********************************
835 @c * GNU Free Documentation License *
836 @c **********************************
838 @c GNU Free Documentation License
839 @cindex GNU Free Documentation License
841 @node Index,,GNU Free Documentation License, Top