1 \input texinfo @c -*-texinfo-*-
3 @c oooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooo
5 @c GNAT DOCUMENTATION o
7 @c G N A T C O D I N G S T Y L E o
11 @c Copyright (C) 1992-2001 Ada Core Technologies, Inc. o
13 @c GNAT is free software; you can redistribute it and/or modify it under o
14 @c terms of the GNU General Public License as published by the Free Soft- o
15 @c ware Foundation; either version 2, or (at your option) any later ver- o
16 @c sion. GNAT is distributed in the hope that it will be useful, but WITH- o
17 @c OUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY o
18 @c or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License o
19 @c for more details. You should have received a copy of the GNU General o
20 @c Public License distributed with GNAT; see file COPYING. If not, write o
21 @c to the Free Software Foundation, 59 Temple Place - Suite 330, Boston, o
22 @c MA 02111-1307, USA. o
24 @c oooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooo
26 @setfilename gnat-style.info
27 @settitle GNAT Coding Style
28 @dircategory Programming
30 * gnat-style: (gnat-style). GNAT Coding Style
33 @macro syntax{element}
39 @center GNAT Coding Style
41 @center A guide for GNAT developers
42 Copyright (C) 1992-2001 Ada Core Technologies, Inc.
47 @title GNAT Coding Style
48 @subtitle A guide for GNAT developers
49 @subtitle Document revision level $Revision: 1.3 $
50 @author Ada Core Technologies, Inc.
54 @node Top, General, , (dir)
55 @comment node-name, next, previous, up
60 * Declarations and Types::
61 * Expressions and Names::
68 @c -------------------------------------------------------------------------
69 @node General, Lexical Elements, Top, Top
71 @c -------------------------------------------------------------------------
74 Most of GNAT is written in Ada using a consistent style to ensure
75 readability of the code. This document has been written to help
76 maintain this consistent style, while having a large group of developers
80 For the coding style in the C parts of the compiler and run time,
81 see the GNU Coding Guidelines.
84 This document is structured after the Ada Reference manual.
85 Those familiar with that document should be able to quickly
86 lookup style rules for particular constructs.
88 @c -------------------------------------------------------------------------
89 @node Lexical Elements, Declarations and Types, General, Top
90 @section Lexical Elements
91 @c -------------------------------------------------------------------------
93 @subsection Character Set and Separators
94 @c -------------------------------------------------------------------------
98 The character set used should be plain 7-bit ASCII@.
99 The only separators allowed are space and the end-of-line sequence.
100 No other control character or format effector (such as HT, VT, FF)
102 The normal end-of-line sequence is used, which may be LF, CR/LF or CR,
103 depending on the host system. An optional SUB (16#1A#) may be present as the
104 last character in the file on hosts using that character as file terminator.
107 Files that are checked in or distributed should be in host format.
110 A line should never be longer than 79 characters, not counting the line
114 Lines must not have trailing blanks.
117 Indentation is 3 characters per level for if statements, loops, case
118 statements. For exact information on required spacing between lexical
119 elements, see file @file{style.adb}.
123 @subsection Identifiers
124 @c -------------------------------------------------------------------------
127 Identifiers will start with an upper case letter, and each letter following
128 an underscore will be upper case. Short acronyms may be all upper case.
129 All other letters are lower case.
130 An exception is for identifiers matching a foreign language. In particular,
131 we use all lower case where appropriate for C@.
134 Use underscores to separate words in an identifier.
136 @item Try to limit your use of abbreviations in identifiers.
137 It is ok to make a few abbreviations, explain what they mean, and then
138 use them frequently, but don't use lots of obscure abbreviations. An
139 example is the @code{ALI} word which stands for Ada Library
140 Information and is by convention always written in upper-case when
141 used in entity names.
144 procedure Find_ALI_Files;
148 Don't use the variable @samp{I}, use @samp{J} instead, @samp{I} is too
149 easily mixed up with @samp{1} in some fonts. Similarly don't use the
150 variable @samp{O}, which is too easily mixed up with @samp{0}.
153 @subsection Numeric Literals
154 @c -------------------------------------------------------------------------
157 Numeric literals should include underscores where helpful for
163 3.14159_26535_89793_23846
167 @subsection Reserved Words
168 @c -------------------------------------------------------------------------
171 Reserved words use all lower case.
178 The words @samp{Access}, @samp{Delta} and @samp{Digits} are
179 capitalized when used as @syntax{attribute_designator}.
183 @c -------------------------------------------------------------------------
187 Comment start with @samp{-- } (i.e.@: @samp{--} followed by two spaces).
188 The only exception to this rule (i.e.@: one space is tolerated) is when the
189 comment ends with @samp{ --}.
190 It also accepted to have only one space between @samp{--} and the start
191 of the comment when the comment is at the end of a line,
195 Every sentence in a comment should start with an upper-case letter (including
196 the first letter of the comment).
199 When declarations are commented with ``hanging'' comments, i.e.@:
200 comments after the declaration, there is no blank line before the
201 comment, and if it is absolutely necessary to have blank lines within
202 the comments these blank lines @emph{do} have a @samp{--} (unlike the
203 normal rule, which is to use entirely blank lines for separating
204 comment paragraphs). The comment start at same level of indentation
205 as code they are commenting.
209 -- @r{Integer value for storing value of} z
211 -- @r{The previous line was a blank line.}
215 Comments that are dubious or incomplete or comment on possibly
216 wrong or incomplete code should be preceded or followed by @samp{???}@.
219 Comments in a subprogram body must generally be surrounded by blank lines,
220 except after a @samp{begin}:
224 -- @r{Comment for the next statement}
228 -- @r{Comment for the B statement}
234 In sequences of statements, comments at the end of the lines should be
238 My_Identifier := 5; -- @r{First comment}
239 Other_Id := 6; -- @r{Second comment}
243 Short comments that fit on a single line are @emph{not} ended with a
244 period. Comments taking more than a line are punctuated in the normal
248 Comments should focus on why instead of what.
249 Descriptions of what subprograms do go with the specification.
252 Comments describing a subprogram spec should specifically mention the
253 formal argument names. General rule: write a comment that does not
254 depend on the names of things. The names are supplementary, not
255 sufficient, as comments.
258 Do NOT put two spaces after periods in comments.
261 @c -------------------------------------------------------------------------
262 @node Declarations and Types, Expressions and Names, Lexical Elements,Top
263 @section Declarations and Types
264 @c -------------------------------------------------------------------------
268 In entity declarations, colons must be surrounded by spaces. Colons
277 Declarations should be grouped in a logical order.
278 Related groups of declarations may be preceded by a header comment.
281 All local subprograms in a subprogram or package body should be declared
282 before the first local subprogram body.
285 Do not declare discriminated record types where the discriminant is used
286 for constraining an unconstrained array type. (Discriminated
287 records for a variant part are allowed.)
290 Don't declare local entities that hide global entities.
293 Don't declare multiple variables in one declaration that spans lines.
294 Start a new declaration on each line, instead.
297 The @syntax{defining_identifier}s of global declarations serve as
298 comments of a sort. So don't choose terse names, but look for names
299 that give useful information instead.
302 Local names can be shorter, because they are used only within
303 one context, where comments explain their purpose.
308 @c -------------------------------------------------------------------------
309 @node Expressions and Names, Statements, Declarations and Types, Top
310 @section Expressions and Names
311 @c -------------------------------------------------------------------------
316 Every operator must be surrounded by spaces, except for the
317 exponentiation operator.
320 E := A * B**2 + 3 * (C - D);
324 When folding a long line, fold before an operator, not after.
327 Use parentheses where they make the intended order of evaluation clearer:
333 @c -------------------------------------------------------------------------
334 @node Statements, Subprograms, Expressions and Names, Top
336 @c -------------------------------------------------------------------------
338 @subsection Simple and Compound Statements
339 @c -------------------------------------------------------------------------
342 Use only one statement or label per line.
344 A longer @syntax{sequence_of_statements} may be divided in logical
345 groups or separated from surrounding code using a blank line.
348 @subsection If Statements
349 @c -------------------------------------------------------------------------
352 When the @samp{if}, @samp{elsif} or @samp{else} keywords fit on the
353 same line with the condition and the @samp{then} keyword, then the
354 statement is formatted as follows:
357 if @var{condition} then
359 elsif @var{condition} then
367 When the above layout is not possible, @samp{then} should be aligned
368 with @samp{if}, and conditions should preferably be split before an
369 @samp{and} or @samp{or} keyword a follows:
372 if @var{long_condition_that_has_to_be_split}
373 and then @var{continued_on_the_next_line}
380 The @samp{elsif}, @samp{else} and @samp{end if} always line up with
381 the @samp{if} keyword. The preferred location for splitting the line
382 is before @samp{and} or @samp{or}. The continuation of a condition is
383 indented with two spaces or as many as needed to make nesting clear.
384 As exception, if conditions are closely related either of the
385 following is allowed:
388 if x = lakdsjfhlkashfdlkflkdsalkhfsalkdhflkjdsahf
390 x = asldkjhalkdsjfhhfd
395 if x = lakdsjfhlkashfdlkflkdsalkhfsalkdhflkjdsahf or else
396 x = asldkjhalkdsjfhhfd or else
402 Conditions should use short-circuit forms (@samp{and then},
406 Complex conditions in if statements are indented two characters:
409 if @var{this_complex_condition}
410 and then @var{that_other_one}
411 and then @var{one_last_one}
417 Every @samp{if} block is preceded and followed by a blank line, except
418 where it begins or ends a @syntax{sequence_of_statements}.
431 @subsection Case Statements
435 Layout is as below. For long case statements, the extra indentation
436 can be saved by aligning the when clauses with the opening case.
439 case @var{expression} is
440 when @var{condition} =>
442 when @var{condition} =>
448 @subsection Loop Statements
452 When possible, have @samp{for} or @samp{while} on one line with the
453 condition and the @samp{loop} keyword.
456 for J in S'Range loop
462 If the condition is too long, split the condition (see ``If
463 statements'' above) and align @samp{loop} with the @samp{for} or
464 @samp{while} keyword.
467 while @var{long_condition_that_has_to_be_split}
468 and then @var{continued_on_the_next_line}
475 If the @syntax{loop_statement} has an identifier, it is laid out as follows:
478 Outer : while not @var{condition} loop
484 @subsection Block Statements
488 The @samp{declare} (optional), @samp{begin} and @samp{end} statements
489 are aligned, except when the @syntax{block_statement} is named. There
490 is a blank line before the @samp{begin} keyword:
503 @c -------------------------------------------------------------------------
504 @node Subprograms, Packages, Statements, Top
506 @c -------------------------------------------------------------------------
509 @subsection Subprogram Declarations
510 @c -------------------------------------------------------------------------
514 Do not write the @samp{in} for parameters, especially in functions:
517 function Length (S : String) return Integer;
521 When the declaration line for a procedure or a function is too long, fold it.
522 In this case, align the colons, and, for functions, the result type.
528 Pad : Character := Space)
533 The parameter list for a subprogram is preceded by a space:
536 procedure Func (A : Integer);
541 @subsection Subprogram Bodies
542 @c -------------------------------------------------------------------------
546 The functions and procedures should always be sorted alphabetically in
550 All subprograms have a header giving the function name, with the following
558 procedure My_Function is
562 Note that the name in the header is preceded by a single space,
563 not two spaces as for other comments.
566 Every subprogram body must have a preceding @syntax{subprogram_declaration}.
569 If there any declarations in a subprogram, the @samp{begin} keyword is
570 preceded by a blank line.
573 If the declarations in a subprogram contain at least one nested
574 subprogram body, then just before the of the enclosing subprogram
575 @samp{begin}, there is a line:
578 -- @r{Start of processing for @var{Enclosing_Subprogram}}
585 @c -------------------------------------------------------------------------
586 @node Packages, Program Structure, Subprograms, Top
587 @section Packages and Visibility Rules
588 @c -------------------------------------------------------------------------
593 All program units and subprograms have their name at the end:
602 We will use the style of @samp{use}-ing @samp{with}-ed packages, with
603 the context clauses looking like:
611 Names declared in the visible part of packages should be
612 unique, to prevent name clashes when the packages are @samp{use}d.
616 type Entity_Kind is ...;
622 After the file header comment, the context clause and unit specification
623 should be the first thing in a @syntax{program_unit}.
626 @c -------------------------------------------------------------------------
627 @node Program Structure,, Packages, Top
628 @section Program Structure and Compilation Issues
629 @c -------------------------------------------------------------------------
633 Every GNAT source file must be compiled with the @option{-gnatg}
634 switch to check the coding style (Note that you should look at
635 @file{style.adb} to see the lexical rules enforced by
639 Each source file should contain only one compilation unit.
642 Filenames should be 8 characters or less followed by the @samp{.adb}
643 extension for a body or @samp{.ads} for a spec.
646 Unit names should be distinct when krunched to 8 characters
647 (see @file{krunch.ads}) and the filenames should match the unit name,
648 except that they are all lower case.