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-2012, AdaCore o
12
@c oooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooo
14
@setfilename gnat-style.info
17
Copyright @copyright{} 1992-2012, AdaCore
19
Permission is granted to copy, distribute and/or modify this document
20
under the terms of the GNU Free Documentation License, Version 1.3 or
21
any later version published by the Free Software Foundation; with no
22
Invariant Sections, with no Front-Cover Texts and with no Back-Cover
23
Texts. A copy of the license is included in the section entitled
24
``GNU Free Documentation License''.
27
@settitle GNAT Coding Style
28
@setchapternewpage odd
30
@include gcc-common.texi
32
@dircategory Software development
34
* gnat-style: (gnat-style). GNAT Coding Style
37
@macro syntax{element}
43
@titlefont{GNAT Coding Style:}
45
@title A Guide for GNAT Developers
46
@subtitle GNAT, The GNU Ada Compiler
48
@author Ada Core Technologies, Inc.
50
@vskip 0pt plus 1filll
57
@node Top, General, , (dir)
58
@comment node-name, next, previous, up
63
A Guide for GNAT Developers
66
GNAT, The GNU Ada Compiler@*
76
* Declarations and Types::
77
* Expressions and Names::
82
* GNU Free Documentation License::
86
@c -------------------------------------------------------------------------
87
@node General, Lexical Elements, Top, Top
89
@c -------------------------------------------------------------------------
92
Most of GNAT is written in Ada using a consistent style to ensure
93
readability of the code. This document has been written to help
94
maintain this consistent style, while having a large group of developers
97
For the coding style in the C parts of the compiler and run time,
98
see the GNU Coding Guidelines.
100
This document is structured after the @cite{Ada Reference Manual}.
101
Those familiar with that document should be able to quickly
102
lookup style rules for particular constructs.
105
@c -------------------------------------------------------------------------
106
@node Lexical Elements, Declarations and Types, General, Top
107
@section Lexical Elements
108
@c -------------------------------------------------------------------------
109
@cindex Lexical elements
111
@subsection Character Set and Separators
112
@c -------------------------------------------------------------------------
113
@cindex Character set
122
The character set used should be plain 7-bit ASCII@.
123
The only separators allowed are space and the end-of-line sequence.
124
No other control character or format effector (such as @code{HT},
125
@code{VT}, @code{FF})
127
The normal end-of-line sequence is used, which may be
128
@code{LF}, @code{CR/LF} or @code{CR},
129
depending on the host system. An optional @code{SUB}
130
(@code{16#1A#}) may be present as the
131
last character in the file on hosts using that character as file terminator.
134
Files that are checked in or distributed should be in host format.
137
A line should never be longer than 79 characters, not counting the line
141
Lines must not have trailing blanks.
144
Indentation is 3 characters per level for @code{if} statements, loops, and
145
@code{case} statements.
146
For exact information on required spacing between lexical
147
elements, see file @file{style.adb}.
148
@cindex @file{style.adb} file
152
@subsection Identifiers
153
@c -------------------------------------------------------------------------
158
Identifiers will start with an upper case letter, and each letter following
159
an underscore will be upper case.
160
@cindex Casing (for identifiers)
161
Short acronyms may be all upper case.
162
All other letters are lower case.
163
An exception is for identifiers matching a foreign language. In particular,
164
we use all lower case where appropriate for C@.
167
Use underscores to separate words in an identifier.
170
@item Try to limit your use of abbreviations in identifiers.
171
It is ok to make a few abbreviations, explain what they mean, and then
172
use them frequently, but don't use lots of obscure abbreviations. An
173
example is the @code{ALI} word which stands for Ada Library
174
Information and is by convention always written in upper-case when
175
used in entity names.
177
@smallexample @c adanocomment
178
procedure Find_ALI_Files;
182
Don't use the variable name @code{I}, use @code{J} instead; @code{I} is too
183
easily confused with @code{1} in some fonts. Similarly don't use the
184
variable @code{O}, which is too easily mistaken for the number @code{0}.
187
@subsection Numeric Literals
188
@c -------------------------------------------------------------------------
189
@cindex Numeric literals
193
Numeric literals should include underscores where helpful for
200
3.14159_26535_89793_23846
204
@subsection Reserved Words
205
@c -------------------------------------------------------------------------
206
@cindex Reserved words
210
Reserved words use all lower case.
211
@cindex Casing (for reserved words)
213
@smallexample @c adanocomment
218
The words @code{Access}, @code{Delta} and @code{Digits} are
219
capitalized when used as @syntax{attribute_designator}.
223
@c -------------------------------------------------------------------------
228
A comment starts with @code{--} followed by two spaces.
229
The only exception to this rule (i.e.@: one space is tolerated) is when the
230
comment ends with a single space followed by @code{--}.
231
It is also acceptable to have only one space between @code{--} and the start
232
of the comment when the comment is at the end of a line,
236
Every sentence in a comment should start with an upper-case letter (including
237
the first letter of the comment).
238
@cindex Casing (in comments)
241
When declarations are commented with ``hanging'' comments, i.e.@:
242
comments after the declaration, there is no blank line before the
243
comment, and if it is absolutely necessary to have blank lines within
244
the comments, e.g. to make paragraph separations within a single comment,
245
these blank lines @emph{do} have a @code{--} (unlike the
246
normal rule, which is to use entirely blank lines for separating
247
comment paragraphs). The comment starts at same level of indentation
248
as code it is commenting.
249
@cindex Blank lines (in comments)
252
@smallexample @c adanocomment
254
-- Integer value for storing value of z
256
-- The previous line was a blank line.
260
Comments that are dubious or incomplete, or that comment on possibly
261
wrong or incomplete code, should be preceded or followed by @code{???}@.
264
Comments in a subprogram body must generally be surrounded by blank lines.
265
An exception is a comment that follows a line containing a single keyword
266
(@code{begin}, @code{else}, @code{loop}):
268
@smallexample @c adanocomment
271
-- Comment for the next statement
275
-- Comment for the B statement
283
In sequences of statements, comments at the end of the lines should be
285
@cindex Alignment (in comments)
287
@smallexample @c adanocomment
288
My_Identifier := 5; -- First comment
289
Other_Id := 6; -- Second comment
293
Short comments that fit on a single line are @emph{not} ended with a
294
period. Comments taking more than a line are punctuated in the normal
298
Comments should focus on @emph{why} instead of @emph{what}.
299
Descriptions of what subprograms do go with the specification.
302
Comments describing a subprogram spec should specifically mention the
303
formal argument names. General rule: write a comment that does not
304
depend on the names of things. The names are supplementary, not
305
sufficient, as comments.
308
@emph{Do not} put two spaces after periods in comments.
311
@c -------------------------------------------------------------------------
312
@node Declarations and Types, Expressions and Names, Lexical Elements,Top
313
@section Declarations and Types
314
@c -------------------------------------------------------------------------
315
@cindex Declarations and Types
319
In entity declarations, colons must be surrounded by spaces. Colons
321
@cindex Alignment (in declarations)
323
@smallexample @c adanocomment
329
Declarations should be grouped in a logical order.
330
Related groups of declarations may be preceded by a header comment.
333
All local subprograms in a subprogram or package body should be declared
334
before the first local subprogram body.
337
Do not declare local entities that hide global entities.
338
@cindex Hiding of outer entities
341
Do not declare multiple variables in one declaration that spans lines.
342
Start a new declaration on each line, instead.
345
The @syntax{defining_identifier}s of global declarations serve as
346
comments of a sort. So don't choose terse names, but look for names
347
that give useful information instead.
350
Local names can be shorter, because they are used only within
351
one context, where comments explain their purpose.
354
When starting an initialization or default expression on the line that follows
355
the declaration line, use 2 characters for indentation.
357
@smallexample @c adanocomment
359
Function_Name (Parameters, For_Call);
363
If an initialization or default expression needs to be continued on subsequent
364
lines, the continuations should be indented from the start of the expression.
366
@smallexample @c adanocomment
367
Entity1 : Integer := Long_Function_Name
368
(parameters for call);
374
@c -------------------------------------------------------------------------
375
@node Expressions and Names, Statements, Declarations and Types, Top
376
@section Expressions and Names
377
@c -------------------------------------------------------------------------
378
@cindex Expressions and names
383
Every operator must be surrounded by spaces. An exception is that
384
this rule does not apply to the exponentiation operator, for which
385
there are no specific layout rules. The reason for this exception
386
is that sometimes it makes clearer reading to leave out the spaces
387
around exponentiation.
390
@smallexample @c adanocomment
391
E := A * B**2 + 3 * (C - D);
395
Use parentheses where they clarify the intended association of operands
397
@cindex Parenthesization of expressions
398
@smallexample @c adanocomment
403
@c -------------------------------------------------------------------------
404
@node Statements, Subprograms, Expressions and Names, Top
406
@c -------------------------------------------------------------------------
409
@subsection Simple and Compound Statements
410
@c -------------------------------------------------------------------------
411
@cindex Simple and compound statements
415
Use only one statement or label per line.
417
A longer @syntax{sequence_of_statements} may be divided in logical
418
groups or separated from surrounding code using a blank line.
421
@subsection If Statements
422
@c -------------------------------------------------------------------------
423
@cindex @code{if} statement
427
When the @code{if}, @code{elsif} or @code{else} keywords fit on the
428
same line with the condition and the @code{then} keyword, then the
429
statement is formatted as follows:
430
@cindex Alignment (in an @code{if} statement)
432
@smallexample @c adanocomment
434
if @var{condition} then
436
elsif @var{condition} then
445
When the above layout is not possible, @code{then} should be aligned
446
with @code{if}, and conditions should preferably be split before an
447
@code{and} or @code{or} keyword a follows:
449
@smallexample @c adanocomment
451
if @var{long_condition_that_has_to_be_split}
452
and then @var{continued_on_the_next_line}
460
The @code{elsif}, @code{else} and @code{end if} always line up with
461
the @code{if} keyword. The preferred location for splitting the line
462
is before @code{and} or @code{or}. The continuation of a condition is
463
indented with two spaces or as many as needed to make nesting clear.
464
As an exception, if conditions are closely related either of the
465
following is allowed:
469
if x = lakdsjfhlkashfdlkflkdsalkhfsalkdhflkjdsahf
471
x = asldkjhalkdsjfhhfd
480
if x = lakdsjfhlkashfdlkflkdsalkhfsalkdhflkjdsahf or else
481
x = asldkjhalkdsjfhhfd or else
490
Conditions should use short-circuit forms (@code{and then},
491
@code{or else}), except when the operands are boolean variables
492
or boolean constants.
493
@cindex Short-circuit forms
496
Complex conditions in @code{if} statements are indented two characters:
497
@cindex Indentation (in @code{if} statements)
499
@smallexample @c adanocomment
501
if @var{this_complex_condition}
502
and then @var{that_other_one}
503
and then @var{one_last_one}
511
There are some cases where complex conditionals can be laid out
512
in manners that do not follow these rules to preserve better
513
parallelism between branches, e.g.
515
@smallexample @c adanocomment
517
if xyz.abc (gef) = 'c'
528
Every @code{if} block is preceded and followed by a blank line, except
529
where it begins or ends a @syntax{sequence_of_statements}.
530
@cindex Blank lines (in an @code{if} statement)
532
@smallexample @c adanocomment
545
@subsection Case Statements
546
@cindex @code{case} statements
550
Layout is as below. For long @code{case} statements, the extra indentation
551
can be saved by aligning the @code{when} clauses with the opening @code{case}.
553
@smallexample @c adanocomment
555
case @var{expression} is
556
when @var{condition} =>
558
when @var{condition} =>
565
@subsection Loop Statements
566
@cindex Loop statements
570
When possible, have @code{for} or @code{while} on one line with the
571
condition and the @code{loop} keyword.
573
@smallexample @c adanocomment
575
for J in S'Range loop
582
If the condition is too long, split the condition (see ``If
583
statements'' above) and align @code{loop} with the @code{for} or
584
@code{while} keyword.
585
@cindex Alignment (in a loop statement)
587
@smallexample @c adanocomment
589
while @var{long_condition_that_has_to_be_split}
590
and then @var{continued_on_the_next_line}
598
If the @syntax{loop_statement} has an identifier, it is laid out as follows:
600
@smallexample @c adanocomment
602
Outer : while not @var{condition} loop
609
@subsection Block Statements
610
@cindex Block statement
614
The @code{declare} (optional), @code{begin} and @code{end} words
615
are aligned, except when the @syntax{block_statement} is named. There
616
is a blank line before the @code{begin} keyword:
617
@cindex Alignment (in a block statement)
619
@smallexample @c adanocomment
632
@c -------------------------------------------------------------------------
633
@node Subprograms, Packages, Statements, Top
635
@c -------------------------------------------------------------------------
638
@subsection Subprogram Declarations
639
@c -------------------------------------------------------------------------
643
Do not write the @code{in} for parameters.
645
@smallexample @c adanocomment
646
function Length (S : String) return Integer;
650
When the declaration line for a procedure or a function is too long to fit
651
the entire declaration (including the keyword procedure or function) on a
652
single line, then fold it, putting a single parameter on a line, aligning
655
@smallexample @c adanocomment
657
procedure Set_Heading
660
Pad : Character := Space;
661
Fill : Boolean := True);
666
In the case of a function, if the entire spec does not fit on one line, then
667
the return may appear after the last parameter, as in:
669
@smallexample @c adanocomment
674
Pad : Character := Space) return String;
679
Or it may appear on its own as a separate line. This form is preferred when
680
putting the return on the same line as the last parameter would result in
681
an overlong line. The return type may optionally be aligned with the types
682
of the parameters (usually we do this aligning if it results only in a small
683
number of extra spaces, and otherwise we don't attempt to align). So two
684
alternative forms for the above spec are:
686
@smallexample @c adanocomment
691
Pad : Character := Space)
697
Pad : Character := Space)
704
@subsection Subprogram Bodies
705
@c -------------------------------------------------------------------------
706
@cindex Subprogram bodies
710
Function and procedure bodies should usually be sorted alphabetically. Do
711
not attempt to sort them in some logical order by functionality. For a
712
sequence of subprogram specs, a general alphabetical sorting is also
713
usually appropriate, but occasionally it makes sense to group by major
714
function, with appropriate headers.
717
All subprograms have a header giving the function name, with the following
720
@smallexample @c adanocomment
726
procedure My_Function is
734
Note that the name in the header is preceded by a single space,
735
not two spaces as for other comments. These headers are used on
736
nested subprograms as well as outer level subprograms. They may
737
also be used as headers for sections of comments, or collections
738
of declarations that are related.
741
Every subprogram body must have a preceding @syntax{subprogram_declaration},
742
which includes proper client documentation so that you do not need to
743
read the subprogram body in order to understand what the subprogram does and
744
how to call it. All subprograms should be documented, without exceptions.
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 the body has no blank lines, and we include it
753
if the declarative part is long or if the body has blank lines.
756
If the declarations in a subprogram contain at least one nested
757
subprogram body, then just before the @code{begin} of the enclosing
758
subprogram, there is a comment line and a blank line:
760
@smallexample @c adanocomment
762
-- Start of processing for @var{Enclosing_Subprogram}
766
end @var{Enclosing_Subprogram};
771
When nested subprograms are present, variables that are referenced by any
772
nested subprogram should precede the nested subprogram specs. For variables
773
that are not referenced by nested procedures, the declarations can either also
774
be before any of the nested subprogram specs (this is the old style, more
775
generally used). Or then can come just before the begin, with a header. The
776
following example shows the two possible styles:
778
@smallexample @c adanocomment
781
Var_Referenced_In_Nested : Integer;
782
Var_Referenced_Only_In_Style1 : Integer;
797
-- Start of processing for Style1
807
Var_Referenced_In_Nested : Integer;
823
Var_Referenced_Only_In_Style2 : Integer;
825
-- Start of processing for Style2
835
For new code, we generally prefer Style2, but we do not insist on
836
modifying all legacy occurrences of Style1, which is still much
837
more common in the sources.
842
@c -------------------------------------------------------------------------
843
@node Packages, Program Structure, Subprograms, Top
844
@section Packages and Visibility Rules
845
@c -------------------------------------------------------------------------
850
All program units and subprograms have their name at the end:
852
@smallexample @c adanocomment
861
We will use the style of @code{use}-ing @code{with}-ed packages, with
862
the context clauses looking like:
863
@cindex @code{use} clauses
865
@smallexample @c adanocomment
873
Names declared in the visible part of packages should be
874
unique, to prevent name clashes when the packages are @code{use}d.
875
@cindex Name clash avoidance
877
@smallexample @c adanocomment
880
type Entity_Kind is ...;
887
After the file header comment, the context clause and unit specification
888
should be the first thing in a @syntax{program_unit}.
891
Preelaborate, Pure and Elaborate_Body pragmas should be added right after the
892
package name, indented an extra level and using the parameterless form:
894
@smallexample @c adanocomment
896
package Preelaborate_Package is
899
end Preelaborate_Package;
905
@c -------------------------------------------------------------------------
906
@node Program Structure, GNU Free Documentation License, Packages, Top
907
@section Program Structure and Compilation Issues
908
@c -------------------------------------------------------------------------
909
@cindex Program structure
913
Every GNAT source file must be compiled with the @option{-gnatg}
914
switch to check the coding style.
915
(Note that you should look at
916
@file{style.adb} to see the lexical rules enforced by
918
@cindex @option{-gnatg} option (to gcc)
919
@cindex @file{style.adb} file
922
Each source file should contain only one compilation unit.
925
Filenames should be 8 or fewer characters, followed by the @code{.adb}
926
extension for a body or @code{.ads} for a spec.
927
@cindex File name length
930
Unit names should be distinct when ``krunch''ed to 8 characters
931
(see @file{krunch.ads}) and the filenames should match the unit name,
932
except that they are all lower case.
933
@cindex @file{krunch.ads} file
937
@c **********************************
938
@c * GNU Free Documentation License *
939
@c **********************************
940
@node GNU Free Documentation License,Index, Program Structure, Top
941
@unnumberedsec GNU Free Documentation License
942
@set nodefaultgnufreedocumentationlicensenode
944
@c GNU Free Documentation License
945
@cindex GNU Free Documentation License
947
@node Index,,GNU Free Documentation License, Top
added
removed
.pc/from-debian-gcc-rename-info-files.diff/gcc/ada/gnat-style.texi
