This is the mail archive of the
gcc-patches@gcc.gnu.org
mailing list for the GCC project.
Re: [Ada] Add GNAT Coding Style Guidelines
- To: "Joseph S. Myers" <jsm28 at cam dot ac dot uk>
- Subject: Re: [Ada] Add GNAT Coding Style Guidelines
- From: Florian Weimer <fw at deneb dot enyo dot de>
- Date: Wed, 07 Nov 2001 16:36:26 +0100
- Cc: Geert Bosch <bosch at gnat dot com>, <gcc-patches at gcc dot gnu dot org>
- References: <Pine.LNX.4.33.0110120125530.21330-100000@kern.srcf.societies.cam.ac.uk>
The following patch addresses most of the issues raised by Joseph
S. Myers and me.
Still open:
> For manuals, the GFDL (using gcc/doc/include/fdl.texi) is more appropriate
> than the GPL.
(I can't decide such stuff, obviously)
> What about the verb in the first sentence of a subprogram description?
> Should it be an imperative or not? An example from the Ada Reference
> Manual:
>
> | 100. function Slice (Source : in Bounded_String;
> | Low : in Positive;
> | High : in Natural)
> | return String;
> |
> | 101. Returns the slice at positions Low through High in the string
> | represented by Source; propagates Index_Error if Low >
> | Length(Source)+1.
>
> I think you could write "Return the slice...", too. Or you could
> repeat the function name. Perhaps a preference should be documented?
> > + @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.)
>
> Why this rule? The other rules are quite obvious or subject to taste,
> but this one seems to be different. Is it a code generation issue?
2001-11-07 Florian Weimer <fw@deneb.enyo.de>
* gnat-style.texi (header): Add @dircategory, @direntry.
(title page): Remove date.
(general) Add @./@: where approriate, and two spaces after the
full stop at the end of a sentence. Use @samp markup when
referring concrete lexical entities (keywords, attribute names
etc.), and @syntax for ARM grammar elements. Use @r for English
text in comments. Use @emph for emphasis. Change "if-statements"
etc. to "if statements" (without @samp). Break long lines. Make
casing of section names consistent.
(Identifiers): Use @samp markup for variable names.
(Comments): Use @samp markup for comment characters. Line-end
comments may follow any Ada code, not just statements. Fix
misspelling of "Integer" as "integer".
(Loop statements): Do not use variable name "I", use "J".
(Subprogram Declarations): Document alignment.
(Subprogram Bodies, Block statements): Document empty line before
"begin".
Index: gnat-style.texi
===================================================================
RCS file: /cvs/gcc/egcs/gcc/ada/gnat-style.texi,v
retrieving revision 1.2
diff -c -r1.2 gnat-style.texi
*** gnat-style.texi 2001/10/28 12:55:50 1.2
--- gnat-style.texi 2001/11/07 15:12:34
***************
*** 25,30 ****
--- 25,38 ----
@setfilename gnat-style.info
@settitle GNAT Coding Style
+ @dircategory Programming
+ @direntry
+ * gnat-syle: (gnat-syle). GNAT Coding Style
+ @end direntry
+
+ @macro syntax{element}
+ @t{\element\}
+ @end macro
@c %**end of header
@ifinfo
***************
*** 39,45 ****
@title GNAT Coding Stye
@subtitle A guide for GNAT developers
@subtitle Document revision level $Revision: 1.2 $
- @subtitle Date: @today{}
@author Ada Core Technologies, Inc.
@end titlepage
@raisesections
--- 47,52 ----
***************
*** 65,71 ****
@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.
--- 72,78 ----
@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.
***************
*** 88,99 ****
@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
--- 95,106 ----
@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
***************
*** 107,114 ****
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
--- 114,121 ----
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
***************
*** 120,144 ****
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
--- 127,153 ----
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 @samp{I}, use @samp{J} instead, @samp{I} is too
! easily mixed up with @samp{1} in some fonts. Similarly don't use the
! variable @samp{O}, which is too easily mixed up with @samp{0}.
@end itemize
@subsection Numeric Literals
***************
*** 166,173 ****
@end smallexample
@item
! The words "Access", "Delta" and "Digits" are capitalized when used
! as attribute_designator.
@end itemize
@subsection Comments
--- 175,182 ----
@end smallexample
@item
! The words @samp{Access}, @samp{Delta} and @samp{Digits} are
! capitalized when used as @syntax{attribute_designator}.
@end itemize
@subsection Comments
***************
*** 175,221 ****
@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
--- 184,231 ----
@itemize @bullet
@item
! Comment start with @samp{-- } (i.e.@: @samp{--} followed by two spaces).
! The only exception to this rule (i.e.@: one space is tolerated) is when the
! comment ends with @samp{ --}.
! It also accepted to have only one space between @samp{--} 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).
@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 @emph{do} have a @samp{--} (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;
! -- @r{Integer value for storing value of} z
--
! -- @r{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 @samp{???}@.
@item
Comments in a subprogram body must generally be surrounded by blank lines,
! except after a @samp{begin}:
@smallexample
begin
! -- @r{Comment for the next statement}
A := 5;
! -- @r{Comment for the B statement}
B := 6;
@end smallexample
***************
*** 225,237 ****
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.
--- 235,248 ----
aligned.
@smallexample
! My_Identifier := 5; -- @r{First comment}
! Other_Id := 6; -- @r{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 why instead of what.
***************
*** 239,246 ****
@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
--- 250,257 ----
@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
***************
*** 254,260 ****
@itemize @bullet
@item
! In entity declarations, colons must be surrounded by spaces. Colons
should be aligned.
@smallexample
--- 265,271 ----
@itemize @bullet
@item
! In entity declarations, colons must be surrounded by spaces. Colons
should be aligned.
@smallexample
***************
*** 272,278 ****
@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
--- 283,289 ----
@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
***************
*** 280,291 ****
@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
--- 291,302 ----
@item
Don't 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
***************
*** 330,350 ****
@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
...
--- 341,362 ----
@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 -------------------------------------------------------------------------
@itemize @bullet
@item
! When the @samp{if}, @samp{elsif} or @samp{else} keywords fit on the
! same line with the condition and the @samp{then} keyword, then the
! statement is formatted as follows:
@smallexample
! if @var{condition} then
...
! elsif @var{condition} then
...
else
...
***************
*** 352,376 ****
@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
! preferred 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
--- 364,388 ----
@end smallexample
@noindent
! When the above layout is not possible, @samp{then} should be aligned
! with @samp{if}, and conditions should preferably be split before an
! @samp{and} or @samp{or} keyword a follows:
@smallexample
! if @var{long_condition_that_has_to_be_split}
! and then @var{continued_on_the_next_line}
then
...
end if;
@end smallexample
@noindent
! The @samp{elsif}, @samp{else} and @samp{end if} always line up with
! the @samp{if} keyword. The preferred location for splitting the line
! is before @samp{and} or @samp{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
***************
*** 387,408 ****
@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;
--- 399,421 ----
@end smallexample
@item
! Conditions should use short-circuit forms (@samp{and then},
! @samp{or else}).
@item
! Complex conditions in if statements are indented two characters:
@smallexample
! if @var{this_complex_condition}
! and then @var{that_other_one}
! and then @var{one_last_one}
then
...
@end smallexample
@item
! Every @samp{if} block is preceded and followed by a blank line, except
! where it begins or ends a @syntax{sequence_of_statements}.
@smallexample
A := 5;
***************
*** 415,467 ****
@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
--- 428,481 ----
@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 @var{expression} is
! when @var{condition} =>
...
! when @var{condition} =>
...
end case;
@end smallexample
@end itemize
! @subsection Loop Statements
@itemize @bullet
@noindent
! When possible, have @samp{for} or @samp{while} on one line with the
! condition and the @samp{loop} keyword.
@smallexample
! for J in S'Range loop
...
end loop;
@end smallexample
@noindent
! If the condition is too long, split the condition (see ``If
! statements'' above) and align @samp{loop} with the @samp{for} or
! @samp{while} keyword.
@smallexample
! while @var{long_condition_that_has_to_be_split}
! and then @var{continued_on_the_next_line}
loop
...
end loop;
@end smallexample
@noindent
! If the @syntax{loop_statement} has an identifier, it is laid out as follows:
@smallexample
! Outer : while not @var{condition} loop
...
end Outer;
@end smallexample
***************
*** 471,482 ****
@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;
--- 485,498 ----
@itemize @bullet
@item
! The @samp{declare} (optional), @samp{begin} and @samp{end} statements
! are aligned, except when the @syntax{block_statement} is named. There
! is a blank line before the @samp{begin} keyword:
@smallexample
Some_Block : declare
...
+
begin
...
end Some_Block;
***************
*** 495,501 ****
@itemize @bullet
@item
! Do not write the "in" for parameters, especially in functions:
@smallexample
function Length (S : String) return Integer;
--- 511,517 ----
@itemize @bullet
@item
! Do not write the @samp{in} for parameters, especially in functions:
@smallexample
function Length (S : String) return Integer;
***************
*** 503,508 ****
--- 519,525 ----
@item
When the declaration line for a procedure or a function is too long, fold it.
+ In this case, align the colons, and, for functions, the result type.
@smallexample
function Head
***************
*** 541,558 ****
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
--- 558,581 ----
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 @syntax{subprogram_declaration}.
+
@item
! If there any declarations in a subprogram, the @samp{begin} keyword is
! preceded by a blank line.
@item
! If the declarations in a subprogram contain at least one nested
! subprogram body, then just before the of the enclosing subprogram
! @samp{begin}, there is a line:
@smallexample
! -- @r{Start of processing for @var{Enclosing_Subprogram}}
begin
@end smallexample
***************
*** 576,583 ****
@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;
--- 599,606 ----
@end smallexample
@item
! We will use the style of @samp{use}-ing @samp{with}-ed packages, with
! the context clauses looking like:
@smallexample
with A; use A;
***************
*** 586,592 ****
@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
--- 609,615 ----
@item
Names declared in the visible part of packages should be
! unique, to prevent name clashes when the packages are @samp{use}d.
@smallexample
package Entity is
***************
*** 597,603 ****
@item
After the file header comment, the context clause and unit specification
! should be the first thing in a program_unit.
@end itemize
@c -------------------------------------------------------------------------
--- 620,626 ----
@item
After the file header comment, the context clause and unit specification
! should be the first thing in a @syntax{program_unit}.
@end itemize
@c -------------------------------------------------------------------------
***************
*** 607,622 ****
@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
--- 630,646 ----
@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}).
@item
Each source file should contain only one compilation unit.
@item
! Filenames should be 8 characters or less followed by the @samp{.adb}
! extension for a body or @samp{.ads} for a spec.
@item
Unit names should be distinct when krunched to 8 characters