* gnat-style.texi: New file describing coding guidelines for Ada.
From-SVN: r46198
This commit is contained in:
Geert Bosch
Geert Bosch
parent
a185c30264
commit
c97412e2c8
2 changed files with 631 additions and 0 deletions
|
|
@ -1,3 +1,7 @@
|
|||
2001-10-10 Geert Bosch <bosch@gnat.com>
|
||||
|
||||
* gnat-style.texi: New file describing coding guidelines for Ada.
|
||||
|
||||
2001-10-10 Ed Schonberg <schonber@gnat.com>
|
||||
|
||||
* einfo.adb (Write_Entity_Flags): Elaboration_Entity_Required
|
||||
|
|
|
|||
627
gcc/ada/gnat-style.texi
Normal file
627
gcc/ada/gnat-style.texi
Normal file
|
|
@ -0,0 +1,627 @@
|
|||
\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 $Revision: 1.1 $
|
||||
@c o
|
||||
@c Copyright (C) 1992-2001 Ada Core Technologies, Inc. o
|
||||
@c o
|
||||
@c GNAT is free software; you can redistribute it and/or modify it under o
|
||||
@c terms of the GNU General Public License as published by the Free Soft- o
|
||||
@c ware Foundation; either version 2, or (at your option) any later ver- o
|
||||
@c sion. GNAT is distributed in the hope that it will be useful, but WITH- o
|
||||
@c OUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY o
|
||||
@c or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License o
|
||||
@c for more details. You should have received a copy of the GNU General o
|
||||
@c Public License distributed with GNAT; see file COPYING. If not, write o
|
||||
@c to the Free Software Foundation, 59 Temple Place - Suite 330, Boston, o
|
||||
@c MA 02111-1307, USA. o
|
||||
@c o
|
||||
@c oooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooo
|
||||
|
||||
@setfilename gnat-style.info
|
||||
@settitle GNAT Coding Style
|
||||
@c %**end of header
|
||||
|
||||
@ifinfo
|
||||
@center GNAT Coding Style
|
||||
|
||||
@center A guide for GNAT developers
|
||||
Copyright (C) 1992-2001 Ada Core Technologies, Inc.
|
||||
@end ifinfo
|
||||
|
||||
@titlepage
|
||||
@sp 10
|
||||
@title GNAT Coding Stye
|
||||
@subtitle A guide for GNAT developers
|
||||
@subtitle Document revision level $Revision: 1.1 $
|
||||
@subtitle Date: @today{}
|
||||
@author Ada Core Technologies, Inc.
|
||||
@end titlepage
|
||||
@raisesections
|
||||
|
||||
@node Top, General, , (dir)
|
||||
@comment node-name, next, previous, up
|
||||
|
||||
@menu
|
||||
* General::
|
||||
* Lexical Elements::
|
||||
* Declarations and Types::
|
||||
* Expressions and Names::
|
||||
* Statements::
|
||||
* Subprograms::
|
||||
* Packages::
|
||||
* Program Structure::
|
||||
@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.
|
||||
|
||||
@noindent
|
||||
For the coding style in the C parts of the compiler and run time,
|
||||
see the GNU Coding Guidelines.
|
||||
|
||||
@noindent
|
||||
This document is structured after the 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 -------------------------------------------------------------------------
|
||||
|
||||
@subsection Character Set and Separators
|
||||
@c -------------------------------------------------------------------------
|
||||
|
||||
@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 HT, VT, FF)
|
||||
should be used.
|
||||
The normal end-of-line sequence is used, which may be LF, CR/LF or CR,
|
||||
depending on the host system. An optional SUB (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 if-statements, loops, case
|
||||
statements. For exact information on required spacing between lexical
|
||||
elements, see file @file{style.adb}.
|
||||
|
||||
@end itemize
|
||||
|
||||
@subsection Identifiers
|
||||
@c -------------------------------------------------------------------------
|
||||
@itemize @bullet
|
||||
@item
|
||||
Identifiers will start with an upper case letter, and each letter following
|
||||
an underscore will be upper case. 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.
|
||||
|
||||
@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
|
||||
procedure Find_ALI_Files;
|
||||
@end smallexample
|
||||
|
||||
@item
|
||||
Don't use the variable I, use J instead, I is too easily mixed up with
|
||||
1 in some fonts. Similarly don't use the variable O, which is too easily
|
||||
mixed up with zero.
|
||||
@end itemize
|
||||
|
||||
@subsection Numeric Literals
|
||||
@c -------------------------------------------------------------------------
|
||||
@itemize @bullet
|
||||
@item
|
||||
Numeric literals should include underscores where helpful for
|
||||
readability.
|
||||
|
||||
@smallexample
|
||||
1_000_000
|
||||
16#8000_000#
|
||||
3.14159_26535_89793_23846
|
||||
@end smallexample
|
||||
@end itemize
|
||||
|
||||
@subsection Reserved Words
|
||||
@c -------------------------------------------------------------------------
|
||||
@itemize @bullet
|
||||
@item
|
||||
Reserved words use all lower case.
|
||||
|
||||
@smallexample
|
||||
return else
|
||||
@end smallexample
|
||||
|
||||
@item
|
||||
The words "Access", "Delta" and "Digits" are capitalized when used
|
||||
as attribute_designator.
|
||||
@end itemize
|
||||
|
||||
@subsection Comments
|
||||
@c -------------------------------------------------------------------------
|
||||
|
||||
@itemize @bullet
|
||||
@item
|
||||
Comment start with @code{-- } (ie @code{--} followed by two spaces).
|
||||
The only exception to this rule (i.e. one space is tolerated) is when the
|
||||
comment ends with @code{--}.
|
||||
It also accepted to have only one space between @code{--} and the start
|
||||
of the comment when the comment is at the end of a line,
|
||||
after an Ada statement.
|
||||
|
||||
@item
|
||||
Every sentence in a comment should start with an upper-case letter (including
|
||||
the first letter of the comment).
|
||||
|
||||
@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
|
||||
these blank lines *do* have a -- (unlike the normal rule, which is to
|
||||
use entirely blank lines for separating comment paragraphs).
|
||||
The comment start at same level of indentation as code they are commenting.
|
||||
|
||||
@smallexample
|
||||
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 comment on possibly
|
||||
wrong or incomplete code should be preceded or followed by ???
|
||||
|
||||
@item
|
||||
Comments in a subprogram body must generally be surrounded by blank lines,
|
||||
except after a "begin":
|
||||
|
||||
@smallexample
|
||||
begin
|
||||
-- Comment for the next statement
|
||||
|
||||
A := 5;
|
||||
|
||||
-- Comment for the B statement
|
||||
|
||||
B := 6;
|
||||
@end smallexample
|
||||
|
||||
@item
|
||||
In sequences of statements, comments at the end of the lines should be
|
||||
aligned.
|
||||
|
||||
@smallexample
|
||||
My_Identifier := 5; -- First comment
|
||||
Other_Id := 6; -- Second comment
|
||||
@end smallexample
|
||||
|
||||
@item
|
||||
Short comments that fit on a single line are NOT ended with a period.
|
||||
Comments taking more than a line are punctuated in the normal manner.
|
||||
|
||||
@item
|
||||
Comments should focus on why instead of 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
|
||||
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 -------------------------------------------------------------------------
|
||||
|
||||
@itemize @bullet
|
||||
@item
|
||||
In entity declarations, colons must be surrounded by spaces. Colons
|
||||
should be aligned.
|
||||
|
||||
@smallexample
|
||||
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 discriminated record types where the discriminant is used
|
||||
for constraining an unconstrained array type. (Discriminated
|
||||
records for a variant part are allowed.)
|
||||
|
||||
@item
|
||||
Don't declare local entities that hide global entities.
|
||||
|
||||
@item
|
||||
Don't declare multiple variables in one declaration that spans lines.
|
||||
Start a new declaration on each line, instead
|
||||
|
||||
@item
|
||||
The defining_identifiers 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.
|
||||
|
||||
@end itemize
|
||||
|
||||
|
||||
@c -------------------------------------------------------------------------
|
||||
@node Expressions and Names, Statements, Declarations and Types, Top
|
||||
@section Expressions and Names
|
||||
@c -------------------------------------------------------------------------
|
||||
|
||||
@itemize @bullet
|
||||
|
||||
@item
|
||||
Every operator must be surrounded by spaces, except for the
|
||||
exponentiation operator.
|
||||
|
||||
@smallexample
|
||||
E := A * B**2 + 3 * (C - D);
|
||||
@end smallexample
|
||||
|
||||
@item
|
||||
When folding a long line, fold before an operator, not after.
|
||||
|
||||
@item
|
||||
Use parentheses where they make the intended order of evaluation clearer:
|
||||
@smallexample
|
||||
(A / B) * C
|
||||
@end smallexample
|
||||
@end itemize
|
||||
|
||||
@c -------------------------------------------------------------------------
|
||||
@node Statements, Subprograms, Expressions and Names, Top
|
||||
@section Statements
|
||||
@c -------------------------------------------------------------------------
|
||||
|
||||
@subsection Simple and Compound Statements
|
||||
@c -------------------------------------------------------------------------
|
||||
@itemize @bullet
|
||||
@item
|
||||
Use only one statement or label per line.
|
||||
@item
|
||||
A longer sequence_of_statements may be divided in logical groups
|
||||
or separated from surrounding code using a blank line.
|
||||
@end itemize
|
||||
|
||||
@subsection If Statements
|
||||
@c -------------------------------------------------------------------------
|
||||
@itemize @bullet
|
||||
@item
|
||||
When the "if", "elsif" or "else" keywords fit on the same line with the
|
||||
condition and the "then" keyword, then the statement is formatted as follows:
|
||||
|
||||
@smallexample
|
||||
if <condition> then
|
||||
...
|
||||
elsif <condition> then
|
||||
...
|
||||
else
|
||||
...
|
||||
end if;
|
||||
@end smallexample
|
||||
|
||||
@noindent
|
||||
When the above layout is not possible, "then" should be aligned with "if",
|
||||
and conditions should preferably be split before an "and" or "or" keyword
|
||||
a follows:
|
||||
|
||||
@smallexample
|
||||
if <long_condition_that_has_to_be_split>
|
||||
and then <continued_on_the_next_line>
|
||||
then
|
||||
...
|
||||
end if;
|
||||
@end smallexample
|
||||
|
||||
@noindent
|
||||
The "elsif", "else" and "end if" always line up with the "if" keyword. The
|
||||
prefered location for splitting the line is before "and" or "or". The
|
||||
continuation of a condition is indented with two spaces or as many as needed
|
||||
to make nesting clear.
|
||||
As exception, if conditions are closely related either of the following is
|
||||
allowed:
|
||||
|
||||
@smallexample
|
||||
if x = lakdsjfhlkashfdlkflkdsalkhfsalkdhflkjdsahf
|
||||
or else
|
||||
x = asldkjhalkdsjfhhfd
|
||||
or else
|
||||
x = asdfadsfadsf
|
||||
then
|
||||
|
||||
if x = lakdsjfhlkashfdlkflkdsalkhfsalkdhflkjdsahf or else
|
||||
x = asldkjhalkdsjfhhfd or else
|
||||
x = asdfadsfadsf
|
||||
then
|
||||
@end smallexample
|
||||
|
||||
@item
|
||||
Conditions should use short-circuit forms ("and then", "or else").
|
||||
|
||||
@item
|
||||
Complex conditions in if-statements are indented two characters:
|
||||
|
||||
@smallexample
|
||||
if this_complex_condition
|
||||
and then that_other_one
|
||||
and then one_last_one
|
||||
then
|
||||
...
|
||||
@end smallexample
|
||||
|
||||
@item
|
||||
Every "if" block is preceded and followed by a blank line, except
|
||||
where it begins or ends a sequence_of_statements.
|
||||
|
||||
@smallexample
|
||||
A := 5;
|
||||
|
||||
if A = 5 then
|
||||
null;
|
||||
end if;
|
||||
|
||||
A := 6;
|
||||
@end smallexample
|
||||
@end itemize
|
||||
|
||||
@subsection Case statements
|
||||
@itemize @bullet
|
||||
|
||||
@item
|
||||
Layout is as below. For long case statements, the extra indentation
|
||||
can be saved by aligning the when clauses with the opening case.
|
||||
|
||||
@smallexample
|
||||
case <expression> is
|
||||
when <condition> =>
|
||||
...
|
||||
when <condition> =>
|
||||
...
|
||||
end case;
|
||||
@end smallexample
|
||||
@end itemize
|
||||
|
||||
@subsection Loop statements
|
||||
@itemize @bullet
|
||||
|
||||
@noindent
|
||||
When possible, have "for" or "while" on one line with the condition
|
||||
and the "loop" keyword.
|
||||
|
||||
@smallexample
|
||||
for I in S'Range loop
|
||||
...
|
||||
end loop;
|
||||
@end smallexample
|
||||
|
||||
@noindent
|
||||
If the condition is too long, split the condition (see if_statement)
|
||||
and align "loop" with the "for" or "while" keyword.
|
||||
|
||||
@smallexample
|
||||
while <long_condition_that_has_to_be_split>
|
||||
and then <continued_on_the_next_line>
|
||||
loop
|
||||
...
|
||||
end loop;
|
||||
@end smallexample
|
||||
|
||||
@noindent
|
||||
If the loop_statement has an identifier, it is layout as follows:
|
||||
|
||||
@smallexample
|
||||
Outer : while not <condition> loop
|
||||
...
|
||||
end Outer;
|
||||
@end smallexample
|
||||
@end itemize
|
||||
|
||||
@subsection Block Statements
|
||||
@itemize @bullet
|
||||
|
||||
@item
|
||||
The (optional) "declare", "begin" and "end" statements are aligned,
|
||||
except when the block_statement is named:
|
||||
|
||||
@smallexample
|
||||
Some_Block : declare
|
||||
...
|
||||
begin
|
||||
...
|
||||
end Some_Block;
|
||||
@end smallexample
|
||||
|
||||
@end itemize
|
||||
|
||||
@c -------------------------------------------------------------------------
|
||||
@node Subprograms, Packages, Statements, Top
|
||||
@section Subprograms
|
||||
@c -------------------------------------------------------------------------
|
||||
|
||||
|
||||
@subsection Subprogram Declarations
|
||||
@c -------------------------------------------------------------------------
|
||||
@itemize @bullet
|
||||
|
||||
@item
|
||||
Do not write the "in" for parameters, especially in functions:
|
||||
|
||||
@smallexample
|
||||
function Length (S : String) return Integer;
|
||||
@end smallexample
|
||||
|
||||
@item
|
||||
When the declaration line for a procedure or a function is too long, fold it.
|
||||
|
||||
@smallexample
|
||||
function Head
|
||||
(Source : String;
|
||||
Count : Natural;
|
||||
Pad : Character := Space)
|
||||
return String;
|
||||
@end smallexample
|
||||
|
||||
@item
|
||||
The parameter list for a subprogram is preceded by a space:
|
||||
|
||||
@smallexample
|
||||
procedure Func (A : Integer);
|
||||
@end smallexample
|
||||
|
||||
@end itemize
|
||||
|
||||
@subsection Subprogram Bodies
|
||||
@c -------------------------------------------------------------------------
|
||||
@itemize @bullet
|
||||
|
||||
@item
|
||||
The functions and procedures should always be sorted alphabetically in
|
||||
a compilation unit.
|
||||
|
||||
@item
|
||||
All subprograms have a header giving the function name, with the following
|
||||
format:
|
||||
|
||||
@smallexample
|
||||
-----------------
|
||||
-- My_Function --
|
||||
-----------------
|
||||
|
||||
procedure My_Function is
|
||||
begin
|
||||
@end smallexample
|
||||
Note that the name in the header is preceded by a single space,
|
||||
not two spaces as for other comments.
|
||||
|
||||
@item
|
||||
Every subprogram body must have a preceding subprogram_declaration.
|
||||
|
||||
@item
|
||||
If declarations of a subprogram contain at least one nested subprogram
|
||||
body, then just before the begin is a line:
|
||||
|
||||
@smallexample
|
||||
-- Start of processing for bla bla
|
||||
|
||||
begin
|
||||
@end smallexample
|
||||
|
||||
@end itemize
|
||||
|
||||
@c -------------------------------------------------------------------------
|
||||
@node Packages, Program Structure, Subprograms, Top
|
||||
@section Packages and Visibility Rules
|
||||
@c -------------------------------------------------------------------------
|
||||
|
||||
@itemize @bullet
|
||||
|
||||
@item
|
||||
All program units and subprograms have their name at the end:
|
||||
|
||||
@smallexample
|
||||
package P is
|
||||
...
|
||||
end P;
|
||||
@end smallexample
|
||||
|
||||
@item
|
||||
We will use the style of use-ing with-ed packages, with the context
|
||||
clauses looking like:
|
||||
|
||||
@smallexample
|
||||
with A; use A;
|
||||
with B; use B;
|
||||
@end smallexample
|
||||
|
||||
@item
|
||||
Names declared in the visible part of packages should be
|
||||
unique, to prevent name clashes when the packages are "use"d.
|
||||
|
||||
@smallexample
|
||||
package Entity is
|
||||
type Entity_Kind is ...;
|
||||
...
|
||||
end Entity;
|
||||
@end smallexample
|
||||
|
||||
@item
|
||||
After the file header comment, the context clause and unit specification
|
||||
should be the first thing in a program_unit.
|
||||
@end itemize
|
||||
|
||||
@c -------------------------------------------------------------------------
|
||||
@node Program Structure,, Packages, Top
|
||||
@section Program Structure and Compilation Issues
|
||||
@c -------------------------------------------------------------------------
|
||||
|
||||
@itemize @bullet
|
||||
@item
|
||||
Every GNAT source file must be compiled with the "-gnatg" switch to check
|
||||
the coding style (Note that you should look at @file{style.adb} to
|
||||
see the lexical rules enforced by -gnatg).
|
||||
|
||||
@item
|
||||
Each source file should contain only one compilation unit.
|
||||
|
||||
@item
|
||||
Filenames should be 8 characters or less followed by the ".adb" extension
|
||||
for a body or ".ads" for a spec.
|
||||
|
||||
@item
|
||||
Unit names should be distinct when krunched to 8 characters
|
||||
(see @file{krunch.ads}) and the filenames should match the unit name,
|
||||
except that they are all lower case.
|
||||
@end itemize
|
||||
|
||||
@bye
|
||||
Loading…
Add table
Reference in a new issue