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
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 @author Ada Core Technologies, Inc.
53 @node Top, General, , (dir)
54 @comment node-name, next, previous, up
59 * Declarations and Types::
60 * Expressions and Names::
67 @c -------------------------------------------------------------------------
68 @node General, Lexical Elements, Top, Top
70 @c -------------------------------------------------------------------------
73 Most of GNAT is written in Ada using a consistent style to ensure
74 readability of the code. This document has been written to help
75 maintain this consistent style, while having a large group of developers
79 For the coding style in the C parts of the compiler and run time,
80 see the GNU Coding Guidelines.
83 This document is structured after the Ada Reference manual.
84 Those familiar with that document should be able to quickly
85 lookup style rules for particular constructs.
87 @c -------------------------------------------------------------------------
88 @node Lexical Elements, Declarations and Types, General, Top
89 @section Lexical Elements
90 @c -------------------------------------------------------------------------
92 @subsection Character Set and Separators
93 @c -------------------------------------------------------------------------
97 The character set used should be plain 7-bit ASCII@.
98 The only separators allowed are space and the end-of-line sequence.
99 No other control character or format effector (such as HT, VT, FF)
101 The normal end-of-line sequence is used, which may be LF, CR/LF or CR,
102 depending on the host system. An optional SUB (16#1A#) may be present as the
103 last character in the file on hosts using that character as file terminator.
106 Files that are checked in or distributed should be in host format.
109 A line should never be longer than 79 characters, not counting the line
113 Lines must not have trailing blanks.
116 Indentation is 3 characters per level for if statements, loops, case
117 statements. For exact information on required spacing between lexical
118 elements, see file @file{style.adb}.
122 @subsection Identifiers
123 @c -------------------------------------------------------------------------
126 Identifiers will start with an upper case letter, and each letter following
127 an underscore will be upper case. Short acronyms may be all upper case.
128 All other letters are lower case.
129 An exception is for identifiers matching a foreign language. In particular,
130 we use all lower case where appropriate for C@.
133 Use underscores to separate words in an identifier.
135 @item Try to limit your use of abbreviations in identifiers.
136 It is ok to make a few abbreviations, explain what they mean, and then
137 use them frequently, but don't use lots of obscure abbreviations. An
138 example is the @code{ALI} word which stands for Ada Library
139 Information and is by convention always written in upper-case when
140 used in entity names.
143 procedure Find_ALI_Files;
147 Don't use the variable @samp{I}, use @samp{J} instead, @samp{I} is too
148 easily mixed up with @samp{1} in some fonts. Similarly don't use the
149 variable @samp{O}, which is too easily mixed up with the number @samp{0}.
152 @subsection Numeric Literals
153 @c -------------------------------------------------------------------------
156 Numeric literals should include underscores where helpful for
162 3.14159_26535_89793_23846
166 @subsection Reserved Words
167 @c -------------------------------------------------------------------------
170 Reserved words use all lower case.
177 The words @samp{Access}, @samp{Delta} and @samp{Digits} are
178 capitalized when used as @syntax{attribute_designator}.
182 @c -------------------------------------------------------------------------
186 Comment start with @samp{-- } (i.e.@: @samp{--} followed by two spaces).
187 The only exception to this rule (i.e.@: one space is tolerated) is when the
188 comment ends with @samp{ --}.
189 It also accepted to have only one space between @samp{--} and the start
190 of the comment when the comment is at the end of a line,
194 Every sentence in a comment should start with an upper-case letter (including
195 the first letter of the comment).
198 When declarations are commented with ``hanging'' comments, i.e.@:
199 comments after the declaration, there is no blank line before the
200 comment, and if it is absolutely necessary to have blank lines within
201 the comments these blank lines @emph{do} have a @samp{--} (unlike the
202 normal rule, which is to use entirely blank lines for separating
203 comment paragraphs). The comment start at same level of indentation
204 as code they are commenting.
208 -- @r{Integer value for storing value of} z
210 -- @r{The previous line was a blank line.}
214 Comments that are dubious or incomplete or comment on possibly
215 wrong or incomplete code should be preceded or followed by @samp{???}@.
218 Comments in a subprogram body must generally be surrounded by blank lines,
219 except after a @samp{begin}:
223 -- @r{Comment for the next statement}
227 -- @r{Comment for the B statement}
233 In sequences of statements, comments at the end of the lines should be
237 My_Identifier := 5; -- @r{First comment}
238 Other_Id := 6; -- @r{Second comment}
242 Short comments that fit on a single line are @emph{not} ended with a
243 period. Comments taking more than a line are punctuated in the normal
247 Comments should focus on why instead of what.
248 Descriptions of what subprograms do go with the specification.
251 Comments describing a subprogram spec should specifically mention the
252 formal argument names. General rule: write a comment that does not
253 depend on the names of things. The names are supplementary, not
254 sufficient, as comments.
257 Do NOT put two spaces after periods in comments.
260 @c -------------------------------------------------------------------------
261 @node Declarations and Types, Expressions and Names, Lexical Elements,Top
262 @section Declarations and Types
263 @c -------------------------------------------------------------------------
267 In entity declarations, colons must be surrounded by spaces. Colons
276 Declarations should be grouped in a logical order.
277 Related groups of declarations may be preceded by a header comment.
280 All local subprograms in a subprogram or package body should be declared
281 before the first local subprogram body.
284 Don't declare local entities that hide global entities.
287 Don't declare multiple variables in one declaration that spans lines.
288 Start a new declaration on each line, instead.
291 The @syntax{defining_identifier}s of global declarations serve as
292 comments of a sort. So don't choose terse names, but look for names
293 that give useful information instead.
296 Local names can be shorter, because they are used only within
297 one context, where comments explain their purpose.
302 @c -------------------------------------------------------------------------
303 @node Expressions and Names, Statements, Declarations and Types, Top
304 @section Expressions and Names
305 @c -------------------------------------------------------------------------
310 Every operator must be surrounded by spaces, except for the
311 exponentiation operator.
314 E := A * B**2 + 3 * (C - D);
318 When folding a long line, fold before an operator, not after.
321 Use parentheses where they clarify the intended association of operands
328 @c -------------------------------------------------------------------------
329 @node Statements, Subprograms, Expressions and Names, Top
331 @c -------------------------------------------------------------------------
333 @subsection Simple and Compound Statements
334 @c -------------------------------------------------------------------------
337 Use only one statement or label per line.
339 A longer @syntax{sequence_of_statements} may be divided in logical
340 groups or separated from surrounding code using a blank line.
343 @subsection If Statements
344 @c -------------------------------------------------------------------------
347 When the @samp{if}, @samp{elsif} or @samp{else} keywords fit on the
348 same line with the condition and the @samp{then} keyword, then the
349 statement is formatted as follows:
352 if @var{condition} then
354 elsif @var{condition} then
362 When the above layout is not possible, @samp{then} should be aligned
363 with @samp{if}, and conditions should preferably be split before an
364 @samp{and} or @samp{or} keyword a follows:
367 if @var{long_condition_that_has_to_be_split}
368 and then @var{continued_on_the_next_line}
375 The @samp{elsif}, @samp{else} and @samp{end if} always line up with
376 the @samp{if} keyword. The preferred location for splitting the line
377 is before @samp{and} or @samp{or}. The continuation of a condition is
378 indented with two spaces or as many as needed to make nesting clear.
379 As exception, if conditions are closely related either of the
380 following is allowed:
383 if x = lakdsjfhlkashfdlkflkdsalkhfsalkdhflkjdsahf
385 x = asldkjhalkdsjfhhfd
390 if x = lakdsjfhlkashfdlkflkdsalkhfsalkdhflkjdsahf or else
391 x = asldkjhalkdsjfhhfd or else
397 Conditions should use short-circuit forms (@samp{and then},
401 Complex conditions in if statements are indented two characters:
404 if @var{this_complex_condition}
405 and then @var{that_other_one}
406 and then @var{one_last_one}
412 Every @samp{if} block is preceded and followed by a blank line, except
413 where it begins or ends a @syntax{sequence_of_statements}.
426 @subsection Case Statements
430 Layout is as below. For long case statements, the extra indentation
431 can be saved by aligning the when clauses with the opening case.
434 case @var{expression} is
435 when @var{condition} =>
437 when @var{condition} =>
443 @subsection Loop Statements
447 When possible, have @samp{for} or @samp{while} on one line with the
448 condition and the @samp{loop} keyword.
451 for J in S'Range loop
457 If the condition is too long, split the condition (see ``If
458 statements'' above) and align @samp{loop} with the @samp{for} or
459 @samp{while} keyword.
462 while @var{long_condition_that_has_to_be_split}
463 and then @var{continued_on_the_next_line}
470 If the @syntax{loop_statement} has an identifier, it is laid out as follows:
473 Outer : while not @var{condition} loop
479 @subsection Block Statements
483 The @samp{declare} (optional), @samp{begin} and @samp{end} statements
484 are aligned, except when the @syntax{block_statement} is named. There
485 is a blank line before the @samp{begin} keyword:
498 @c -------------------------------------------------------------------------
499 @node Subprograms, Packages, Statements, Top
501 @c -------------------------------------------------------------------------
504 @subsection Subprogram Declarations
505 @c -------------------------------------------------------------------------
509 Do not write the @samp{in} for parameters, especially in functions:
512 function Length (S : String) return Integer;
516 When the declaration line for a procedure or a function is too long, fold it.
517 In this case, align the colons, and, for functions, the result type.
523 Pad : Character := Space)
528 The parameter list for a subprogram is preceded by a space:
531 procedure Func (A : Integer);
536 @subsection Subprogram Bodies
537 @c -------------------------------------------------------------------------
541 The functions and procedures should always be sorted alphabetically in
545 All subprograms have a header giving the function name, with the following
553 procedure My_Function is
557 Note that the name in the header is preceded by a single space,
558 not two spaces as for other comments.
561 Every subprogram body must have a preceding @syntax{subprogram_declaration}.
564 If there any declarations in a subprogram, the @samp{begin} keyword is
565 preceded by a blank line.
568 If the declarations in a subprogram contain at least one nested
569 subprogram body, then just before the @samp{begin} of the enclosing
570 subprogram, there is a line:
573 -- @r{Start of processing for @var{Enclosing_Subprogram}}
580 @c -------------------------------------------------------------------------
581 @node Packages, Program Structure, Subprograms, Top
582 @section Packages and Visibility Rules
583 @c -------------------------------------------------------------------------
588 All program units and subprograms have their name at the end:
597 We will use the style of @samp{use}-ing @samp{with}-ed packages, with
598 the context clauses looking like:
606 Names declared in the visible part of packages should be
607 unique, to prevent name clashes when the packages are @samp{use}d.
611 type Entity_Kind is ...;
617 After the file header comment, the context clause and unit specification
618 should be the first thing in a @syntax{program_unit}.
621 @c -------------------------------------------------------------------------
622 @node Program Structure,, Packages, Top
623 @section Program Structure and Compilation Issues
624 @c -------------------------------------------------------------------------
628 Every GNAT source file must be compiled with the @option{-gnatg}
629 switch to check the coding style (Note that you should look at
630 @file{style.adb} to see the lexical rules enforced by
634 Each source file should contain only one compilation unit.
637 Filenames should be 8 characters or less followed by the @samp{.adb}
638 extension for a body or @samp{.ads} for a spec.
641 Unit names should be distinct when krunched to 8 characters
642 (see @file{krunch.ads}) and the filenames should match the unit name,
643 except that they are all lower case.