diff options
author | upstream source tree <ports@midipix.org> | 2015-03-15 20:14:05 -0400 |
---|---|---|
committer | upstream source tree <ports@midipix.org> | 2015-03-15 20:14:05 -0400 |
commit | 554fd8c5195424bdbcabf5de30fdc183aba391bd (patch) | |
tree | 976dc5ab7fddf506dadce60ae936f43f58787092 /gcc/ada/gnat-style.texi | |
download | cbb-gcc-4.6.4-15d2061ac0796199866debe9ac87130894b0cdd3.tar.bz2 cbb-gcc-4.6.4-15d2061ac0796199866debe9ac87130894b0cdd3.tar.xz |
obtained gcc-4.6.4.tar.bz2 from upstream website;upstream
verified gcc-4.6.4.tar.bz2.sig;
imported gcc-4.6.4 source tree from verified upstream tarball.
downloading a git-generated archive based on the 'upstream' tag
should provide you with a source tree that is binary identical
to the one extracted from the above tarball.
if you have obtained the source via the command 'git clone',
however, do note that line-endings of files in your working
directory might differ from line-endings of the respective
files in the upstream repository.
Diffstat (limited to 'gcc/ada/gnat-style.texi')
-rw-r--r-- | gcc/ada/gnat-style.texi | 930 |
1 files changed, 930 insertions, 0 deletions
diff --git a/gcc/ada/gnat-style.texi b/gcc/ada/gnat-style.texi new file mode 100644 index 000000000..13eb1ed1f --- /dev/null +++ b/gcc/ada/gnat-style.texi @@ -0,0 +1,930 @@ +\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 GNAT is maintained by Ada Core Technologies Inc (http://www.gnat.com). o +@c o +@c oooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooo + +@setfilename gnat-style.info + +@copying +Copyright @copyright{} 1992-2008, Free Software Foundation, Inc. + +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_000# + 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. + +@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 +@noindent +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}. + +@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 ********************************** +@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 |