955 lines
26 KiB
Plaintext
955 lines
26 KiB
Plaintext
\input texinfo @c -*-texinfo-*-
|
|
@c %**start of header
|
|
|
|
@c oooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooo
|
|
@c o
|
|
@c GNAT DOCUMENTATION o
|
|
@c o
|
|
@c G N A T C O D I N G S T Y L E o
|
|
@c o
|
|
@c Copyright (C) 1992-2012, AdaCore o
|
|
@c o
|
|
@c oooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooo
|
|
|
|
@setfilename gnat-style.info
|
|
|
|
@copying
|
|
Copyright @copyright{} 1992-2012, AdaCore
|
|
|
|
Permission is granted to copy, distribute and/or modify this document
|
|
under the terms of the GNU Free Documentation License, Version 1.3 or
|
|
any later version published by the Free Software Foundation; with no
|
|
Invariant Sections, with no Front-Cover Texts and with no Back-Cover
|
|
Texts. A copy of the license is included in the section entitled
|
|
``GNU Free Documentation License''.
|
|
@end copying
|
|
|
|
@settitle GNAT Coding Style
|
|
@setchapternewpage odd
|
|
|
|
@include gcc-common.texi
|
|
|
|
@dircategory Software development
|
|
@direntry
|
|
* gnat-style: (gnat-style). GNAT Coding Style
|
|
@end direntry
|
|
|
|
@macro syntax{element}
|
|
@t{\element\}
|
|
@end macro
|
|
@c %**end of header
|
|
|
|
@titlepage
|
|
@titlefont{GNAT Coding Style:}
|
|
@sp 1
|
|
@title A Guide for GNAT Developers
|
|
@subtitle GNAT, The GNU Ada Compiler
|
|
@versionsubtitle
|
|
@author Ada Core Technologies, Inc.
|
|
@page
|
|
@vskip 0pt plus 1filll
|
|
|
|
@insertcopying
|
|
@end titlepage
|
|
|
|
@raisesections
|
|
|
|
@node Top, General, , (dir)
|
|
@comment node-name, next, previous, up
|
|
|
|
@ifnottex
|
|
@noindent
|
|
GNAT Coding Style@*
|
|
A Guide for GNAT Developers
|
|
@sp 2
|
|
@noindent
|
|
GNAT, The GNU Ada Compiler@*
|
|
|
|
@noindent
|
|
@insertcopying
|
|
@end ifnottex
|
|
|
|
|
|
@menu
|
|
* General::
|
|
* Lexical Elements::
|
|
* Declarations and Types::
|
|
* Expressions and Names::
|
|
* Statements::
|
|
* Subprograms::
|
|
* Packages::
|
|
* Program Structure::
|
|
* GNU Free Documentation License::
|
|
* Index::
|
|
@end menu
|
|
|
|
@c -------------------------------------------------------------------------
|
|
@node General, Lexical Elements, Top, Top
|
|
@section General
|
|
@c -------------------------------------------------------------------------
|
|
|
|
@noindent
|
|
Most of GNAT is written in Ada using a consistent style to ensure
|
|
readability of the code. This document has been written to help
|
|
maintain this consistent style, while having a large group of developers
|
|
work on the compiler.
|
|
|
|
For the coding style in the C parts of the compiler and run time,
|
|
see the GNU Coding Guidelines.
|
|
|
|
This document is structured after the @cite{Ada Reference Manual}.
|
|
Those familiar with that document should be able to quickly
|
|
lookup style rules for particular constructs.
|
|
|
|
|
|
@c -------------------------------------------------------------------------
|
|
@node Lexical Elements, Declarations and Types, General, Top
|
|
@section Lexical Elements
|
|
@c -------------------------------------------------------------------------
|
|
@cindex Lexical elements
|
|
|
|
@subsection Character Set and Separators
|
|
@c -------------------------------------------------------------------------
|
|
@cindex Character set
|
|
@cindex ASCII
|
|
@cindex Separators
|
|
@cindex End-of-line
|
|
@cindex Line length
|
|
@cindex Indentation
|
|
|
|
@itemize @bullet
|
|
@item
|
|
The character set used should be plain 7-bit ASCII@.
|
|
The only separators allowed are space and the end-of-line sequence.
|
|
No other control character or format effector (such as @code{HT},
|
|
@code{VT}, @code{FF})
|
|
should be used.
|
|
The normal end-of-line sequence is used, which may be
|
|
@code{LF}, @code{CR/LF} or @code{CR},
|
|
depending on the host system. An optional @code{SUB}
|
|
(@code{16#1A#}) may be present as the
|
|
last character in the file on hosts using that character as file terminator.
|
|
|
|
@item
|
|
Files that are checked in or distributed should be in host format.
|
|
|
|
@item
|
|
A line should never be longer than 79 characters, not counting the line
|
|
separator.
|
|
|
|
@item
|
|
Lines must not have trailing blanks.
|
|
|
|
@item
|
|
Indentation is 3 characters per level for @code{if} statements, loops, and
|
|
@code{case} statements.
|
|
For exact information on required spacing between lexical
|
|
elements, see file @file{style.adb}.
|
|
@cindex @file{style.adb} file
|
|
@end itemize
|
|
|
|
|
|
@subsection Identifiers
|
|
@c -------------------------------------------------------------------------
|
|
@itemize @bullet
|
|
@cindex Identifiers
|
|
|
|
@item
|
|
Identifiers will start with an upper case letter, and each letter following
|
|
an underscore will be upper case.
|
|
@cindex Casing (for identifiers)
|
|
Short acronyms may be all upper case.
|
|
All other letters are lower case.
|
|
An exception is for identifiers matching a foreign language. In particular,
|
|
we use all lower case where appropriate for C@.
|
|
|
|
@item
|
|
Use underscores to separate words in an identifier.
|
|
@cindex Underscores
|
|
|
|
@item Try to limit your use of abbreviations in identifiers.
|
|
It is ok to make a few abbreviations, explain what they mean, and then
|
|
use them frequently, but don't use lots of obscure abbreviations. An
|
|
example is the @code{ALI} word which stands for Ada Library
|
|
Information and is by convention always written in upper-case when
|
|
used in entity names.
|
|
|
|
@smallexample @c adanocomment
|
|
procedure Find_ALI_Files;
|
|
@end smallexample
|
|
|
|
@item
|
|
Don't use the variable name @code{I}, use @code{J} instead; @code{I} is too
|
|
easily confused with @code{1} in some fonts. Similarly don't use the
|
|
variable @code{O}, which is too easily mistaken for the number @code{0}.
|
|
@end itemize
|
|
|
|
@subsection Numeric Literals
|
|
@c -------------------------------------------------------------------------
|
|
@cindex Numeric literals
|
|
|
|
@itemize @bullet
|
|
@item
|
|
Numeric literals should include underscores where helpful for
|
|
readability.
|
|
@cindex Underscores
|
|
|
|
@smallexample
|
|
1_000_000
|
|
16#8000_0000#
|
|
3.14159_26535_89793_23846
|
|
@end smallexample
|
|
@end itemize
|
|
|
|
@subsection Reserved Words
|
|
@c -------------------------------------------------------------------------
|
|
@cindex Reserved words
|
|
|
|
@itemize @bullet
|
|
@item
|
|
Reserved words use all lower case.
|
|
@cindex Casing (for reserved words)
|
|
|
|
@smallexample @c adanocomment
|
|
return else
|
|
@end smallexample
|
|
|
|
@item
|
|
The words @code{Access}, @code{Delta} and @code{Digits} are
|
|
capitalized when used as @syntax{attribute_designator}.
|
|
@end itemize
|
|
|
|
@subsection Comments
|
|
@c -------------------------------------------------------------------------
|
|
@cindex Comments
|
|
|
|
@itemize @bullet
|
|
@item
|
|
A comment starts with @code{--} followed by two spaces.
|
|
The only exception to this rule (i.e.@: one space is tolerated) is when the
|
|
comment ends with a single space followed by @code{--}.
|
|
It is also acceptable to have only one space between @code{--} and the start
|
|
of the comment when the comment is at the end of a line,
|
|
after some Ada code.
|
|
|
|
@item
|
|
Every sentence in a comment should start with an upper-case letter (including
|
|
the first letter of the comment).
|
|
@cindex Casing (in comments)
|
|
|
|
@item
|
|
When declarations are commented with ``hanging'' comments, i.e.@:
|
|
comments after the declaration, there is no blank line before the
|
|
comment, and if it is absolutely necessary to have blank lines within
|
|
the comments, e.g. to make paragraph separations within a single comment,
|
|
these blank lines @emph{do} have a @code{--} (unlike the
|
|
normal rule, which is to use entirely blank lines for separating
|
|
comment paragraphs). The comment starts at same level of indentation
|
|
as code it is commenting.
|
|
@cindex Blank lines (in comments)
|
|
@cindex Indentation
|
|
|
|
@smallexample @c adanocomment
|
|
z : Integer;
|
|
-- Integer value for storing value of z
|
|
--
|
|
-- The previous line was a blank line.
|
|
@end smallexample
|
|
|
|
@item
|
|
Comments that are dubious or incomplete, or that comment on possibly
|
|
wrong or incomplete code, should be preceded or followed by @code{???}@.
|
|
|
|
@item
|
|
Comments in a subprogram body must generally be surrounded by blank lines.
|
|
An exception is a comment that follows a line containing a single keyword
|
|
(@code{begin}, @code{else}, @code{loop}):
|
|
|
|
@smallexample @c adanocomment
|
|
@group
|
|
begin
|
|
-- Comment for the next statement
|
|
|
|
A := 5;
|
|
|
|
-- Comment for the B statement
|
|
|
|
B := 6;
|
|
end;
|
|
@end group
|
|
@end smallexample
|
|
|
|
@item
|
|
In sequences of statements, comments at the end of the lines should be
|
|
aligned.
|
|
@cindex Alignment (in comments)
|
|
|
|
@smallexample @c adanocomment
|
|
My_Identifier := 5; -- First comment
|
|
Other_Id := 6; -- Second comment
|
|
@end smallexample
|
|
|
|
@item
|
|
Short comments that fit on a single line are @emph{not} ended with a
|
|
period. Comments taking more than a line are punctuated in the normal
|
|
manner.
|
|
|
|
@item
|
|
Comments should focus on @emph{why} instead of @emph{what}.
|
|
Descriptions of what subprograms do go with the specification.
|
|
|
|
@item
|
|
Comments describing a subprogram spec should specifically mention the
|
|
formal argument names. General rule: write a comment that does not
|
|
depend on the names of things. The names are supplementary, not
|
|
sufficient, as comments.
|
|
|
|
@item
|
|
@emph{Do not} put two spaces after periods in comments.
|
|
@end itemize
|
|
|
|
@c -------------------------------------------------------------------------
|
|
@node Declarations and Types, Expressions and Names, Lexical Elements,Top
|
|
@section Declarations and Types
|
|
@c -------------------------------------------------------------------------
|
|
@cindex Declarations and Types
|
|
|
|
@itemize @bullet
|
|
@item
|
|
In entity declarations, colons must be surrounded by spaces. Colons
|
|
should be aligned.
|
|
@cindex Alignment (in declarations)
|
|
|
|
@smallexample @c adanocomment
|
|
Entity1 : Integer;
|
|
My_Entity : Integer;
|
|
@end smallexample
|
|
|
|
@item
|
|
Declarations should be grouped in a logical order.
|
|
Related groups of declarations may be preceded by a header comment.
|
|
|
|
@item
|
|
All local subprograms in a subprogram or package body should be declared
|
|
before the first local subprogram body.
|
|
|
|
@item
|
|
Do not declare local entities that hide global entities.
|
|
@cindex Hiding of outer entities
|
|
|
|
@item
|
|
Do not declare multiple variables in one declaration that spans lines.
|
|
Start a new declaration on each line, instead.
|
|
|
|
@item
|
|
The @syntax{defining_identifier}s of global declarations serve as
|
|
comments of a sort. So don't choose terse names, but look for names
|
|
that give useful information instead.
|
|
|
|
@item
|
|
Local names can be shorter, because they are used only within
|
|
one context, where comments explain their purpose.
|
|
|
|
@item
|
|
When starting an initialization or default expression on the line that follows
|
|
the declaration line, use 2 characters for indentation.
|
|
|
|
@smallexample @c adanocomment
|
|
Entity1 : Integer :=
|
|
Function_Name (Parameters, For_Call);
|
|
@end smallexample
|
|
|
|
@item
|
|
If an initialization or default expression needs to be continued on subsequent
|
|
lines, the continuations should be indented from the start of the expression.
|
|
|
|
@smallexample @c adanocomment
|
|
Entity1 : Integer := Long_Function_Name
|
|
(parameters for call);
|
|
@end smallexample
|
|
|
|
@end itemize
|
|
|
|
|
|
@c -------------------------------------------------------------------------
|
|
@node Expressions and Names, Statements, Declarations and Types, Top
|
|
@section Expressions and Names
|
|
@c -------------------------------------------------------------------------
|
|
@cindex Expressions and names
|
|
|
|
@itemize @bullet
|
|
|
|
@item
|
|
Every operator must be surrounded by spaces. An exception is that
|
|
this rule does not apply to the exponentiation operator, for which
|
|
there are no specific layout rules. The reason for this exception
|
|
is that sometimes it makes clearer reading to leave out the spaces
|
|
around exponentiation.
|
|
@cindex Operators
|
|
|
|
@smallexample @c adanocomment
|
|
E := A * B**2 + 3 * (C - D);
|
|
@end smallexample
|
|
|
|
@item
|
|
Use parentheses where they clarify the intended association of operands
|
|
with operators:
|
|
@cindex Parenthesization of expressions
|
|
@smallexample @c adanocomment
|
|
(A / B) * C
|
|
@end smallexample
|
|
@end itemize
|
|
|
|
@c -------------------------------------------------------------------------
|
|
@node Statements, Subprograms, Expressions and Names, Top
|
|
@section Statements
|
|
@c -------------------------------------------------------------------------
|
|
@cindex Statements
|
|
|
|
@subsection Simple and Compound Statements
|
|
@c -------------------------------------------------------------------------
|
|
@cindex Simple and compound statements
|
|
|
|
@itemize @bullet
|
|
@item
|
|
Use only one statement or label per line.
|
|
@item
|
|
A longer @syntax{sequence_of_statements} may be divided in logical
|
|
groups or separated from surrounding code using a blank line.
|
|
@end itemize
|
|
|
|
@subsection If Statements
|
|
@c -------------------------------------------------------------------------
|
|
@cindex @code{if} statement
|
|
|
|
@itemize @bullet
|
|
@item
|
|
When the @code{if}, @code{elsif} or @code{else} keywords fit on the
|
|
same line with the condition and the @code{then} keyword, then the
|
|
statement is formatted as follows:
|
|
@cindex Alignment (in an @code{if} statement)
|
|
|
|
@smallexample @c adanocomment
|
|
@group
|
|
if @var{condition} then
|
|
...
|
|
elsif @var{condition} then
|
|
...
|
|
else
|
|
...
|
|
end if;
|
|
@end group
|
|
@end smallexample
|
|
|
|
@noindent
|
|
When the above layout is not possible, @code{then} should be aligned
|
|
with @code{if}, and conditions should preferably be split before an
|
|
@code{and} or @code{or} keyword a follows:
|
|
|
|
@smallexample @c adanocomment
|
|
@group
|
|
if @var{long_condition_that_has_to_be_split}
|
|
and then @var{continued_on_the_next_line}
|
|
then
|
|
...
|
|
end if;
|
|
@end group
|
|
@end smallexample
|
|
|
|
@noindent
|
|
The @code{elsif}, @code{else} and @code{end if} always line up with
|
|
the @code{if} keyword. The preferred location for splitting the line
|
|
is before @code{and} or @code{or}. The continuation of a condition is
|
|
indented with two spaces or as many as needed to make nesting clear.
|
|
As an exception, if conditions are closely related either of the
|
|
following is allowed:
|
|
|
|
@smallexample
|
|
@group
|
|
if x = lakdsjfhlkashfdlkflkdsalkhfsalkdhflkjdsahf
|
|
or else
|
|
x = asldkjhalkdsjfhhfd
|
|
or else
|
|
x = asdfadsfadsf
|
|
then
|
|
...
|
|
end if;
|
|
@end group
|
|
|
|
@group
|
|
if x = lakdsjfhlkashfdlkflkdsalkhfsalkdhflkjdsahf or else
|
|
x = asldkjhalkdsjfhhfd or else
|
|
x = asdfadsfadsf
|
|
then
|
|
...
|
|
end if;
|
|
@end group
|
|
@end smallexample
|
|
|
|
@item
|
|
Conditions should use short-circuit forms (@code{and then},
|
|
@code{or else}), except when the operands are boolean variables
|
|
or boolean constants.
|
|
@cindex Short-circuit forms
|
|
|
|
@item
|
|
Complex conditions in @code{if} statements are indented two characters:
|
|
@cindex Indentation (in @code{if} statements)
|
|
|
|
@smallexample @c adanocomment
|
|
@group
|
|
if @var{this_complex_condition}
|
|
and then @var{that_other_one}
|
|
and then @var{one_last_one}
|
|
then
|
|
...
|
|
end if;
|
|
@end group
|
|
@end smallexample
|
|
|
|
@noindent
|
|
There are some cases where complex conditionals can be laid out
|
|
in manners that do not follow these rules to preserve better
|
|
parallelism between branches, e.g.
|
|
|
|
@smallexample @c adanocomment
|
|
@group
|
|
if xyz.abc (gef) = 'c'
|
|
or else
|
|
xyz.abc (gef) = 'x'
|
|
then
|
|
...
|
|
end if;
|
|
@end group
|
|
@end smallexample
|
|
|
|
|
|
@item
|
|
Every @code{if} block is preceded and followed by a blank line, except
|
|
where it begins or ends a @syntax{sequence_of_statements}.
|
|
@cindex Blank lines (in an @code{if} statement)
|
|
|
|
@smallexample @c adanocomment
|
|
@group
|
|
A := 5;
|
|
|
|
if A = 5 then
|
|
null;
|
|
end if;
|
|
|
|
A := 6;
|
|
@end group
|
|
@end smallexample
|
|
@end itemize
|
|
|
|
@subsection Case Statements
|
|
@cindex @code{case} statements
|
|
|
|
@itemize @bullet
|
|
@item
|
|
Layout is as below. For long @code{case} statements, the extra indentation
|
|
can be saved by aligning the @code{when} clauses with the opening @code{case}.
|
|
|
|
@smallexample @c adanocomment
|
|
@group
|
|
case @var{expression} is
|
|
when @var{condition} =>
|
|
...
|
|
when @var{condition} =>
|
|
...
|
|
end case;
|
|
@end group
|
|
@end smallexample
|
|
@end itemize
|
|
|
|
@subsection Loop Statements
|
|
@cindex Loop statements
|
|
|
|
@itemize @bullet
|
|
@item
|
|
When possible, have @code{for} or @code{while} on one line with the
|
|
condition and the @code{loop} keyword.
|
|
|
|
@smallexample @c adanocomment
|
|
@group
|
|
for J in S'Range loop
|
|
...
|
|
end loop;
|
|
@end group
|
|
@end smallexample
|
|
|
|
@noindent
|
|
If the condition is too long, split the condition (see ``If
|
|
statements'' above) and align @code{loop} with the @code{for} or
|
|
@code{while} keyword.
|
|
@cindex Alignment (in a loop statement)
|
|
|
|
@smallexample @c adanocomment
|
|
@group
|
|
while @var{long_condition_that_has_to_be_split}
|
|
and then @var{continued_on_the_next_line}
|
|
loop
|
|
...
|
|
end loop;
|
|
@end group
|
|
@end smallexample
|
|
|
|
@noindent
|
|
If the @syntax{loop_statement} has an identifier, it is laid out as follows:
|
|
|
|
@smallexample @c adanocomment
|
|
@group
|
|
Outer : while not @var{condition} loop
|
|
...
|
|
end Outer;
|
|
@end group
|
|
@end smallexample
|
|
@end itemize
|
|
|
|
@subsection Block Statements
|
|
@cindex Block statement
|
|
|
|
@itemize @bullet
|
|
@item
|
|
The @code{declare} (optional), @code{begin} and @code{end} words
|
|
are aligned, except when the @syntax{block_statement} is named. There
|
|
is a blank line before the @code{begin} keyword:
|
|
@cindex Alignment (in a block statement)
|
|
|
|
@smallexample @c adanocomment
|
|
@group
|
|
Some_Block : declare
|
|
...
|
|
|
|
begin
|
|
...
|
|
end Some_Block;
|
|
@end group
|
|
@end smallexample
|
|
|
|
@end itemize
|
|
|
|
@c -------------------------------------------------------------------------
|
|
@node Subprograms, Packages, Statements, Top
|
|
@section Subprograms
|
|
@c -------------------------------------------------------------------------
|
|
@cindex Subprograms
|
|
|
|
@subsection Subprogram Declarations
|
|
@c -------------------------------------------------------------------------
|
|
@itemize @bullet
|
|
|
|
@item
|
|
Do not write the @code{in} for parameters.
|
|
|
|
@smallexample @c adanocomment
|
|
function Length (S : String) return Integer;
|
|
@end smallexample
|
|
|
|
@item
|
|
When the declaration line for a procedure or a function is too long to fit
|
|
the entire declaration (including the keyword procedure or function) on a
|
|
single line, then fold it, putting a single parameter on a line, aligning
|
|
the colons, as in:
|
|
|
|
@smallexample @c adanocomment
|
|
@group
|
|
procedure Set_Heading
|
|
(Source : String;
|
|
Count : Natural;
|
|
Pad : Character := Space;
|
|
Fill : Boolean := True);
|
|
@end group
|
|
@end smallexample
|
|
|
|
@noindent
|
|
In the case of a function, if the entire spec does not fit on one line, then
|
|
the return may appear after the last parameter, as in:
|
|
|
|
@smallexample @c adanocomment
|
|
@group
|
|
function Head
|
|
(Source : String;
|
|
Count : Natural;
|
|
Pad : Character := Space) return String;
|
|
@end group
|
|
@end smallexample
|
|
|
|
@noindent
|
|
Or it may appear on its own as a separate line. This form is preferred when
|
|
putting the return on the same line as the last parameter would result in
|
|
an overlong line. The return type may optionally be aligned with the types
|
|
of the parameters (usually we do this aligning if it results only in a small
|
|
number of extra spaces, and otherwise we don't attempt to align). So two
|
|
alternative forms for the above spec are:
|
|
|
|
@smallexample @c adanocomment
|
|
@group
|
|
function Head
|
|
(Source : String;
|
|
Count : Natural;
|
|
Pad : Character := Space)
|
|
return String;
|
|
|
|
function Head
|
|
(Source : String;
|
|
Count : Natural;
|
|
Pad : Character := Space)
|
|
return String;
|
|
@end group
|
|
@end smallexample
|
|
|
|
@end itemize
|
|
|
|
@subsection Subprogram Bodies
|
|
@c -------------------------------------------------------------------------
|
|
@cindex Subprogram bodies
|
|
|
|
@itemize @bullet
|
|
@item
|
|
Function and procedure bodies should usually be sorted alphabetically. Do
|
|
not attempt to sort them in some logical order by functionality. For a
|
|
sequence of subprogram specs, a general alphabetical sorting is also
|
|
usually appropriate, but occasionally it makes sense to group by major
|
|
function, with appropriate headers.
|
|
|
|
@item
|
|
All subprograms have a header giving the function name, with the following
|
|
format:
|
|
|
|
@smallexample @c adanocomment
|
|
@group
|
|
-----------------
|
|
-- My_Function --
|
|
-----------------
|
|
|
|
procedure My_Function is
|
|
begin
|
|
...
|
|
end My_Function;
|
|
@end group
|
|
@end smallexample
|
|
|
|
@noindent
|
|
Note that the name in the header is preceded by a single space,
|
|
not two spaces as for other comments. These headers are used on
|
|
nested subprograms as well as outer level subprograms. They may
|
|
also be used as headers for sections of comments, or collections
|
|
of declarations that are related.
|
|
|
|
@item
|
|
Every subprogram body must have a preceding @syntax{subprogram_declaration},
|
|
which includes proper client documentation so that you do not need to
|
|
read the subprogram body in order to understand what the subprogram does and
|
|
how to call it. All subprograms should be documented, without exceptions.
|
|
|
|
@item
|
|
@cindex Blank lines (in subprogram bodies)
|
|
A sequence of declarations may optionally be separated from the following
|
|
begin by a blank line. Just as we optionally allow blank lines in general
|
|
between declarations, this blank line should be present only if it improves
|
|
readability. Generally we avoid this blank line if the declarative part is
|
|
small (one or two lines) and the body has no blank lines, and we include it
|
|
if the declarative part is long or if the body has blank lines.
|
|
|
|
@item
|
|
If the declarations in a subprogram contain at least one nested
|
|
subprogram body, then just before the @code{begin} of the enclosing
|
|
subprogram, there is a comment line and a blank line:
|
|
|
|
@smallexample @c adanocomment
|
|
@group
|
|
-- Start of processing for @var{Enclosing_Subprogram}
|
|
|
|
begin
|
|
...
|
|
end @var{Enclosing_Subprogram};
|
|
@end group
|
|
@end smallexample
|
|
|
|
@item
|
|
When nested subprograms are present, variables that are referenced by any
|
|
nested subprogram should precede the nested subprogram specs. For variables
|
|
that are not referenced by nested procedures, the declarations can either also
|
|
be before any of the nested subprogram specs (this is the old style, more
|
|
generally used). Or then can come just before the begin, with a header. The
|
|
following example shows the two possible styles:
|
|
|
|
@smallexample @c adanocomment
|
|
@group
|
|
procedure Style1 is
|
|
Var_Referenced_In_Nested : Integer;
|
|
Var_Referenced_Only_In_Style1 : Integer;
|
|
|
|
proc Nested;
|
|
-- Comments ...
|
|
|
|
|
|
------------
|
|
-- Nested --
|
|
------------
|
|
|
|
procedure Nested is
|
|
begin
|
|
...
|
|
end Nested;
|
|
|
|
-- Start of processing for Style1
|
|
|
|
begin
|
|
...
|
|
end Style1;
|
|
|
|
@end group
|
|
|
|
@group
|
|
procedure Style2 is
|
|
Var_Referenced_In_Nested : Integer;
|
|
|
|
proc Nested;
|
|
-- Comments ...
|
|
|
|
------------
|
|
-- Nested --
|
|
------------
|
|
|
|
procedure Nested is
|
|
begin
|
|
...
|
|
end Nested;
|
|
|
|
-- Local variables
|
|
|
|
Var_Referenced_Only_In_Style2 : Integer;
|
|
|
|
-- Start of processing for Style2
|
|
|
|
begin
|
|
...
|
|
end Style2;
|
|
|
|
@end group
|
|
@end smallexample
|
|
|
|
@noindent
|
|
For new code, we generally prefer Style2, but we do not insist on
|
|
modifying all legacy occurrences of Style1, which is still much
|
|
more common in the sources.
|
|
|
|
@end itemize
|
|
|
|
|
|
@c -------------------------------------------------------------------------
|
|
@node Packages, Program Structure, Subprograms, Top
|
|
@section Packages and Visibility Rules
|
|
@c -------------------------------------------------------------------------
|
|
@cindex Packages
|
|
|
|
@itemize @bullet
|
|
@item
|
|
All program units and subprograms have their name at the end:
|
|
|
|
@smallexample @c adanocomment
|
|
@group
|
|
package P is
|
|
...
|
|
end P;
|
|
@end group
|
|
@end smallexample
|
|
|
|
@item
|
|
We will use the style of @code{use}-ing @code{with}-ed packages, with
|
|
the context clauses looking like:
|
|
@cindex @code{use} clauses
|
|
|
|
@smallexample @c adanocomment
|
|
@group
|
|
with A; use A;
|
|
with B; use B;
|
|
@end group
|
|
@end smallexample
|
|
|
|
@item
|
|
Names declared in the visible part of packages should be
|
|
unique, to prevent name clashes when the packages are @code{use}d.
|
|
@cindex Name clash avoidance
|
|
|
|
@smallexample @c adanocomment
|
|
@group
|
|
package Entity is
|
|
type Entity_Kind is ...;
|
|
...
|
|
end Entity;
|
|
@end group
|
|
@end smallexample
|
|
|
|
@item
|
|
After the file header comment, the context clause and unit specification
|
|
should be the first thing in a @syntax{program_unit}.
|
|
|
|
@item
|
|
Preelaborate, Pure and Elaborate_Body pragmas should be added right after the
|
|
package name, indented an extra level and using the parameterless form:
|
|
|
|
@smallexample @c adanocomment
|
|
@group
|
|
package Preelaborate_Package is
|
|
pragma Preelaborate;
|
|
...
|
|
end Preelaborate_Package;
|
|
@end group
|
|
@end smallexample
|
|
|
|
@end itemize
|
|
|
|
@c -------------------------------------------------------------------------
|
|
@node Program Structure, GNU Free Documentation License, Packages, Top
|
|
@section Program Structure and Compilation Issues
|
|
@c -------------------------------------------------------------------------
|
|
@cindex Program structure
|
|
|
|
@itemize @bullet
|
|
@item
|
|
Every GNAT source file must be compiled with the @option{-gnatg}
|
|
switch to check the coding style.
|
|
(Note that you should look at
|
|
@file{style.adb} to see the lexical rules enforced by
|
|
@option{-gnatg}).
|
|
@cindex @option{-gnatg} option (to gcc)
|
|
@cindex @file{style.adb} file
|
|
|
|
@item
|
|
Each source file should contain only one compilation unit.
|
|
|
|
@item
|
|
Filenames should be 8 or fewer characters, followed by the @code{.adb}
|
|
extension for a body or @code{.ads} for a spec.
|
|
@cindex File name length
|
|
|
|
@item
|
|
Unit names should be distinct when ``krunch''ed to 8 characters
|
|
(see @file{krunch.ads}) and the filenames should match the unit name,
|
|
except that they are all lower case.
|
|
@cindex @file{krunch.ads} file
|
|
@end itemize
|
|
|
|
|
|
@c **********************************
|
|
@c * GNU Free Documentation License *
|
|
@c **********************************
|
|
@node GNU Free Documentation License,Index, Program Structure, Top
|
|
@unnumberedsec GNU Free Documentation License
|
|
@set nodefaultgnufreedocumentationlicensenode
|
|
@include fdl.texi
|
|
@c GNU Free Documentation License
|
|
@cindex GNU Free Documentation License
|
|
|
|
@node Index,,GNU Free Documentation License, Top
|
|
@unnumberedsec Index
|
|
|
|
@printindex cp
|
|
|
|
@contents
|
|
|
|
@bye
|