diff options
Diffstat (limited to 'gcc-4.4.3/gcc/ada/gnat-style.texi')
| -rw-r--r-- | gcc-4.4.3/gcc/ada/gnat-style.texi | 930 |
1 files changed, 0 insertions, 930 deletions
diff --git a/gcc-4.4.3/gcc/ada/gnat-style.texi b/gcc-4.4.3/gcc/ada/gnat-style.texi deleted file mode 100644 index 37395c722..000000000 --- a/gcc-4.4.3/gcc/ada/gnat-style.texi +++ /dev/null @@ -1,930 +0,0 @@ -\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.2 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 @hfill 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 |