143561Skato\input texinfo @c -*-texinfo-*- 243561Skato@c %**start of header 343561Skato 443561Skato@c oooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooo 543561Skato@c o 643561Skato@c GNAT DOCUMENTATION o 743561Skato@c o 843561Skato@c G N A T C O D I N G S T Y L E o 943561Skato@c o 1043561Skato@c Copyright (C) 1992-2012, AdaCore o 1143561Skato@c o 1243561Skato@c oooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooo 1343561Skato 1443561Skato@setfilename gnat-style.info 1543561Skato 1643561Skato@copying 1743561SkatoCopyright @copyright{} 1992-2012, AdaCore 1843561Skato 1943561SkatoPermission is granted to copy, distribute and/or modify this document 2043561Skatounder the terms of the GNU Free Documentation License, Version 1.3 or 2143561Skatoany later version published by the Free Software Foundation; with no 2243561SkatoInvariant Sections, with no Front-Cover Texts and with no Back-Cover 2343561SkatoTexts. A copy of the license is included in the section entitled 2443561Skato``GNU Free Documentation License''. 2543561Skato@end copying 2643561Skato 2743561Skato@settitle GNAT Coding Style 2843561Skato@setchapternewpage odd 2943561Skato 3043561Skato@include gcc-common.texi 3143561Skato 3243561Skato@dircategory Software development 3343561Skato@direntry 3443561Skato* gnat-style: (gnat-style). GNAT Coding Style 3543561Skato@end direntry 3643561Skato 3743561Skato@macro syntax{element} 3843561Skato@t{\element\} 3943561Skato@end macro 4043561Skato@c %**end of header 4143561Skato 4243561Skato@titlepage 4343561Skato@titlefont{GNAT Coding Style:} 4443561Skato@sp 1 4543561Skato@title A Guide for GNAT Developers 4643561Skato@subtitle GNAT, The GNU Ada Compiler 4743561Skato@versionsubtitle 4843561Skato@author Ada Core Technologies, Inc. 4943561Skato@page 5043561Skato@vskip 0pt plus 1filll 5143561Skato 5243561Skato@insertcopying 5343561Skato@end titlepage 5443561Skato 5543561Skato@raisesections 5643561Skato 5743561Skato@node Top, General, , (dir) 5843561Skato@comment node-name, next, previous, up 5943561Skato 6043561Skato@ifnottex 6143561Skato@noindent 6243561SkatoGNAT Coding Style@* 6343561SkatoA Guide for GNAT Developers 6443561Skato@sp 2 6543561Skato@noindent 6643561SkatoGNAT, The GNU Ada Compiler@* 6743561Skato 6843561Skato@noindent 6943561Skato@insertcopying 7043561Skato@end ifnottex 7143561Skato 7243561Skato 7343561Skato@menu 7443561Skato* General:: 7543561Skato* Lexical Elements:: 7643561Skato* Declarations and Types:: 7743561Skato* Expressions and Names:: 7843561Skato* Statements:: 7943561Skato* Subprograms:: 8043561Skato* Packages:: 8143561Skato* Program Structure:: 8243561Skato* GNU Free Documentation License:: 8343561Skato* Index:: 8443561Skato@end menu 8543561Skato 8643561Skato@c ------------------------------------------------------------------------- 8743561Skato@node General, Lexical Elements, Top, Top 8843561Skato@section General 8943561Skato@c ------------------------------------------------------------------------- 9043561Skato 9143561Skato@noindent 9243561SkatoMost of GNAT is written in Ada using a consistent style to ensure 9343561Skatoreadability of the code. This document has been written to help 9443561Skatomaintain this consistent style, while having a large group of developers 9543561Skatowork on the compiler. 9643561Skato 9743561SkatoFor the coding style in the C parts of the compiler and run time, 9843561Skatosee the GNU Coding Guidelines. 9943561Skato 10043561SkatoThis document is structured after the @cite{Ada Reference Manual}. 10143561SkatoThose familiar with that document should be able to quickly 10243561Skatolookup style rules for particular constructs. 10343561Skato 10443561Skato 10543561Skato@c ------------------------------------------------------------------------- 10643561Skato@node Lexical Elements, Declarations and Types, General, Top 10743561Skato@section Lexical Elements 10843561Skato@c ------------------------------------------------------------------------- 10943561Skato@cindex Lexical elements 11043561Skato 11143561Skato@subsection Character Set and Separators 11243561Skato@c ------------------------------------------------------------------------- 11343561Skato@cindex Character set 11443561Skato@cindex ASCII 11543561Skato@cindex Separators 11643561Skato@cindex End-of-line 11743561Skato@cindex Line length 11843561Skato@cindex Indentation 11943561Skato 12043561Skato@itemize @bullet 12143561Skato@item 12243561SkatoThe character set used should be plain 7-bit ASCII@. 12343561SkatoThe only separators allowed are space and the end-of-line sequence. 12443561SkatoNo other control character or format effector (such as @code{HT}, 12543561Skato@code{VT}, @code{FF}) 12643561Skatoshould be used. 12743561SkatoThe normal end-of-line sequence is used, which may be 12843561Skato@code{LF}, @code{CR/LF} or @code{CR}, 12943561Skatodepending on the host system. An optional @code{SUB} 13043561Skato(@code{16#1A#}) may be present as the 13143561Skatolast character in the file on hosts using that character as file terminator. 13243561Skato 13343561Skato@item 13443561SkatoFiles that are checked in or distributed should be in host format. 13543561Skato 13643561Skato@item 13743561SkatoA line should never be longer than 79 characters, not counting the line 13843561Skatoseparator. 13943561Skato 14043561Skato@item 14143561SkatoLines must not have trailing blanks. 14243561Skato 14343561Skato@item 14443561SkatoIndentation is 3 characters per level for @code{if} statements, loops, and 14543561Skato@code{case} statements. 14643561SkatoFor exact information on required spacing between lexical 14743561Skatoelements, see file @file{style.adb}. 14843561Skato@cindex @file{style.adb} file 14943561Skato@end itemize 15043561Skato 15143561Skato 15243561Skato@subsection Identifiers 15343561Skato@c ------------------------------------------------------------------------- 15443561Skato@itemize @bullet 15543561Skato@cindex Identifiers 15643561Skato 15743561Skato@item 15843561SkatoIdentifiers will start with an upper case letter, and each letter following 15943561Skatoan underscore will be upper case. 16043561Skato@cindex Casing (for identifiers) 16143561SkatoShort acronyms may be all upper case. 16243561SkatoAll other letters are lower case. 16343561SkatoAn exception is for identifiers matching a foreign language. In particular, 16443561Skatowe use all lower case where appropriate for C@. 16543561Skato 16643561Skato@item 16743561SkatoUse underscores to separate words in an identifier. 16843561Skato@cindex Underscores 16943561Skato 17043561Skato@item Try to limit your use of abbreviations in identifiers. 17143561SkatoIt is ok to make a few abbreviations, explain what they mean, and then 17243561Skatouse them frequently, but don't use lots of obscure abbreviations. An 17343561Skatoexample is the @code{ALI} word which stands for Ada Library 17443561SkatoInformation and is by convention always written in upper-case when 17543561Skatoused in entity names. 17643561Skato 17743561Skato@smallexample @c adanocomment 17843561Skato procedure Find_ALI_Files; 17943561Skato@end smallexample 18043561Skato 18143561Skato@item 18243561SkatoDon't use the variable name @code{I}, use @code{J} instead; @code{I} is too 18343561Skatoeasily confused with @code{1} in some fonts. Similarly don't use the 18443561Skatovariable @code{O}, which is too easily mistaken for the number @code{0}. 18543561Skato@end itemize 18643561Skato 18743561Skato@subsection Numeric Literals 18843561Skato@c ------------------------------------------------------------------------- 18943561Skato@cindex Numeric literals 19043561Skato 19143561Skato@itemize @bullet 19243561Skato@item 19343561SkatoNumeric literals should include underscores where helpful for 19443561Skatoreadability. 19543561Skato@cindex Underscores 19643561Skato 19743561Skato@smallexample 19843561Skato 1_000_000 19943561Skato 16#8000_0000# 20043561Skato 3.14159_26535_89793_23846 20143561Skato@end smallexample 20243561Skato@end itemize 20343561Skato 20443561Skato@subsection Reserved Words 20543561Skato@c ------------------------------------------------------------------------- 20643561Skato@cindex Reserved words 20743561Skato 20843561Skato@itemize @bullet 20943561Skato@item 21043561SkatoReserved words use all lower case. 21143561Skato@cindex Casing (for reserved words) 21243561Skato 21343561Skato@smallexample @c adanocomment 21443561Skato return else 21543561Skato@end smallexample 21643561Skato 21743561Skato@item 21843561SkatoThe words @code{Access}, @code{Delta} and @code{Digits} are 21943561Skatocapitalized when used as @syntax{attribute_designator}. 22043561Skato@end itemize 22143561Skato 22243561Skato@subsection Comments 22343561Skato@c ------------------------------------------------------------------------- 22443561Skato@cindex Comments 22543561Skato 22643561Skato@itemize @bullet 22743561Skato@item 22843561SkatoA comment starts with @code{--} followed by two spaces. 22943561SkatoThe only exception to this rule (i.e.@: one space is tolerated) is when the 23043561Skatocomment ends with a single space followed by @code{--}. 23143561SkatoIt is also acceptable to have only one space between @code{--} and the start 23243561Skatoof the comment when the comment is at the end of a line, 23343561Skatoafter some Ada code. 23443561Skato 23543561Skato@item 23643561SkatoEvery sentence in a comment should start with an upper-case letter (including 23743561Skatothe first letter of the comment). 23843561Skato@cindex Casing (in comments) 23943561Skato 24043561Skato@item 24143561SkatoWhen declarations are commented with ``hanging'' comments, i.e.@: 24243561Skatocomments after the declaration, there is no blank line before the 24343561Skatocomment, and if it is absolutely necessary to have blank lines within 24443561Skatothe comments, e.g. to make paragraph separations within a single comment, 24543561Skatothese blank lines @emph{do} have a @code{--} (unlike the 24643561Skatonormal rule, which is to use entirely blank lines for separating 24743561Skatocomment paragraphs). The comment starts at same level of indentation 24843561Skatoas code it is commenting. 24943561Skato@cindex Blank lines (in comments) 25043561Skato@cindex Indentation 25143561Skato 25243561Skato@smallexample @c adanocomment 25343561Skato z : Integer; 25443561Skato -- Integer value for storing value of z 25543561Skato -- 25643561Skato -- The previous line was a blank line. 25743561Skato@end smallexample 25843561Skato 25943561Skato@item 26043561SkatoComments that are dubious or incomplete, or that comment on possibly 26143561Skatowrong or incomplete code, should be preceded or followed by @code{???}@. 26243561Skato 26343561Skato@item 26443561SkatoComments in a subprogram body must generally be surrounded by blank lines. 26543561SkatoAn exception is a comment that follows a line containing a single keyword 26643561Skato(@code{begin}, @code{else}, @code{loop}): 26743561Skato 26843561Skato@smallexample @c adanocomment 26943561Skato@group 27043561Skato begin 27143561Skato -- Comment for the next statement 27243561Skato 27343561Skato A := 5; 27443561Skato 27543561Skato -- Comment for the B statement 27643561Skato 27743561Skato B := 6; 27843561Skato end; 27943561Skato@end group 28043561Skato@end smallexample 28143561Skato 28243561Skato@item 28343561SkatoIn sequences of statements, comments at the end of the lines should be 28443561Skatoaligned. 28543561Skato@cindex Alignment (in comments) 28643561Skato 28743561Skato@smallexample @c adanocomment 28843561Skato My_Identifier := 5; -- First comment 28943561Skato Other_Id := 6; -- Second comment 29043561Skato@end smallexample 29143561Skato 29243561Skato@item 29343561SkatoShort comments that fit on a single line are @emph{not} ended with a 29443561Skatoperiod. Comments taking more than a line are punctuated in the normal 29543561Skatomanner. 29643561Skato 29743561Skato@item 29843561SkatoComments should focus on @emph{why} instead of @emph{what}. 29943561SkatoDescriptions of what subprograms do go with the specification. 30043561Skato 30143561Skato@item 30243561SkatoComments describing a subprogram spec should specifically mention the 30343561Skatoformal argument names. General rule: write a comment that does not 30443561Skatodepend on the names of things. The names are supplementary, not 30543561Skatosufficient, as comments. 30643561Skato 30743561Skato@item 30843561Skato@emph{Do not} put two spaces after periods in comments. 30943561Skato@end itemize 31043561Skato 31143561Skato@c ------------------------------------------------------------------------- 31243561Skato@node Declarations and Types, Expressions and Names, Lexical Elements,Top 31343561Skato@section Declarations and Types 31443561Skato@c ------------------------------------------------------------------------- 31543561Skato@cindex Declarations and Types 31643561Skato 31743561Skato@itemize @bullet 31843561Skato@item 31943561SkatoIn entity declarations, colons must be surrounded by spaces. Colons 32043561Skatoshould be aligned. 32143561Skato@cindex Alignment (in declarations) 32243561Skato 32343561Skato@smallexample @c adanocomment 32443561Skato Entity1 : Integer; 32543561Skato My_Entity : Integer; 32643561Skato@end smallexample 32743561Skato 32843561Skato@item 32943561SkatoDeclarations should be grouped in a logical order. 33043561SkatoRelated groups of declarations may be preceded by a header comment. 33143561Skato 33243561Skato@item 33343561SkatoAll local subprograms in a subprogram or package body should be declared 33443561Skatobefore the first local subprogram body. 33543561Skato 33643561Skato@item 33743561SkatoDo not declare local entities that hide global entities. 33843561Skato@cindex Hiding of outer entities 33943561Skato 34043561Skato@item 34143561SkatoDo not declare multiple variables in one declaration that spans lines. 34243561SkatoStart a new declaration on each line, instead. 34343561Skato 34443561Skato@item 34543561SkatoThe @syntax{defining_identifier}s of global declarations serve as 34643561Skatocomments of a sort. So don't choose terse names, but look for names 34743561Skatothat give useful information instead. 34843561Skato 34943561Skato@item 35043561SkatoLocal names can be shorter, because they are used only within 35143561Skatoone context, where comments explain their purpose. 35243561Skato 35343561Skato@item 35443561SkatoWhen starting an initialization or default expression on the line that follows 35543561Skatothe declaration line, use 2 characters for indentation. 35643561Skato 35743561Skato@smallexample @c adanocomment 35843561Skato Entity1 : Integer := 35943561Skato Function_Name (Parameters, For_Call); 36043561Skato@end smallexample 36143561Skato 36243561Skato@item 36343561SkatoIf an initialization or default expression needs to be continued on subsequent 36443561Skatolines, the continuations should be indented from the start of the expression. 36543561Skato 36643561Skato@smallexample @c adanocomment 36743561Skato Entity1 : Integer := Long_Function_Name 36843561Skato (parameters for call); 36943561Skato@end smallexample 37043561Skato 37143561Skato@end itemize 37243561Skato 37343561Skato 37443561Skato@c ------------------------------------------------------------------------- 37543561Skato@node Expressions and Names, Statements, Declarations and Types, Top 37643561Skato@section Expressions and Names 37743561Skato@c ------------------------------------------------------------------------- 37843561Skato@cindex Expressions and names 37943561Skato 38043561Skato@itemize @bullet 38143561Skato 38243561Skato@item 38343561SkatoEvery operator must be surrounded by spaces. An exception is that 38443561Skatothis rule does not apply to the exponentiation operator, for which 38543561Skatothere are no specific layout rules. The reason for this exception 38643561Skatois that sometimes it makes clearer reading to leave out the spaces 38743561Skatoaround exponentiation. 38843561Skato@cindex Operators 38943561Skato 39043561Skato@smallexample @c adanocomment 39143561Skato E := A * B**2 + 3 * (C - D); 39243561Skato@end smallexample 39343561Skato 39443561Skato@item 39543561SkatoUse parentheses where they clarify the intended association of operands 39643561Skatowith operators: 39743561Skato@cindex Parenthesization of expressions 39843561Skato@smallexample @c adanocomment 39943561Skato (A / B) * C 40043561Skato@end smallexample 40143561Skato@end itemize 40243561Skato 40343561Skato@c ------------------------------------------------------------------------- 40443561Skato@node Statements, Subprograms, Expressions and Names, Top 40543561Skato@section Statements 40643561Skato@c ------------------------------------------------------------------------- 40743561Skato@cindex Statements 40843561Skato 40943561Skato@subsection Simple and Compound Statements 41043561Skato@c ------------------------------------------------------------------------- 41143561Skato@cindex Simple and compound statements 41243561Skato 41343561Skato@itemize @bullet 41443561Skato@item 41543561SkatoUse only one statement or label per line. 41643561Skato@item 41743561SkatoA longer @syntax{sequence_of_statements} may be divided in logical 41843561Skatogroups or separated from surrounding code using a blank line. 41943561Skato@end itemize 42043561Skato 42143561Skato@subsection If Statements 42243561Skato@c ------------------------------------------------------------------------- 42343561Skato@cindex @code{if} statement 42443561Skato 42543561Skato@itemize @bullet 42643561Skato@item 42743561SkatoWhen the @code{if}, @code{elsif} or @code{else} keywords fit on the 42843561Skatosame line with the condition and the @code{then} keyword, then the 42943561Skatostatement is formatted as follows: 43043561Skato@cindex Alignment (in an @code{if} statement) 43143561Skato 43243561Skato@smallexample @c adanocomment 43343561Skato@group 43443561Skato if @var{condition} then 43543561Skato ... 43643561Skato elsif @var{condition} then 43743561Skato ... 43843561Skato else 43943561Skato ... 44043561Skato end if; 44143561Skato@end group 44243561Skato@end smallexample 44343561Skato 44443561Skato@noindent 44543561SkatoWhen the above layout is not possible, @code{then} should be aligned 44643561Skatowith @code{if}, and conditions should preferably be split before an 44743561Skato@code{and} or @code{or} keyword a follows: 44843561Skato 44943561Skato@smallexample @c adanocomment 45043561Skato@group 45143561Skato if @var{long_condition_that_has_to_be_split} 45243561Skato and then @var{continued_on_the_next_line} 45343561Skato then 45443561Skato ... 45543561Skato end if; 45643561Skato@end group 45743561Skato@end smallexample 45843561Skato 45943561Skato@noindent 46043561SkatoThe @code{elsif}, @code{else} and @code{end if} always line up with 46143561Skatothe @code{if} keyword. The preferred location for splitting the line 46243561Skatois before @code{and} or @code{or}. The continuation of a condition is 46343561Skatoindented with two spaces or as many as needed to make nesting clear. 46443561SkatoAs an exception, if conditions are closely related either of the 46543561Skatofollowing is allowed: 46643561Skato 46743561Skato@smallexample 46843561Skato@group 46943561Skato if x = lakdsjfhlkashfdlkflkdsalkhfsalkdhflkjdsahf 47043561Skato or else 47143561Skato x = asldkjhalkdsjfhhfd 47243561Skato or else 47343561Skato x = asdfadsfadsf 47443561Skato then 47543561Skato ... 47643561Skato end if; 47743561Skato@end group 47843561Skato 47943561Skato@group 48043561Skato if x = lakdsjfhlkashfdlkflkdsalkhfsalkdhflkjdsahf or else 48143561Skato x = asldkjhalkdsjfhhfd or else 48243561Skato x = asdfadsfadsf 48343561Skato then 48443561Skato ... 48543561Skato end if; 48643561Skato@end group 48743561Skato@end smallexample 48843561Skato 48943561Skato@item 49043561SkatoConditions should use short-circuit forms (@code{and then}, 49143561Skato@code{or else}), except when the operands are boolean variables 49243561Skatoor boolean constants. 49343561Skato@cindex Short-circuit forms 49443561Skato 49543561Skato@item 49643561SkatoComplex conditions in @code{if} statements are indented two characters: 49743561Skato@cindex Indentation (in @code{if} statements) 49843561Skato 49943561Skato@smallexample @c adanocomment 50043561Skato@group 50143561Skato if @var{this_complex_condition} 50243561Skato and then @var{that_other_one} 50343561Skato and then @var{one_last_one} 50443561Skato then 50543561Skato ... 50643561Skato end if; 50743561Skato@end group 50843561Skato@end smallexample 50943561Skato 51043561Skato@noindent 51143561SkatoThere are some cases where complex conditionals can be laid out 51243561Skatoin manners that do not follow these rules to preserve better 51343561Skatoparallelism between branches, e.g. 51443561Skato 51543561Skato@smallexample @c adanocomment 51643561Skato@group 51743561Skato if xyz.abc (gef) = 'c' 51843561Skato or else 51943561Skato xyz.abc (gef) = 'x' 52043561Skato then 52143561Skato ... 52243561Skato end if; 52343561Skato@end group 52443561Skato@end smallexample 52543561Skato 52643561Skato 52743561Skato@item 52843561SkatoEvery @code{if} block is preceded and followed by a blank line, except 52943561Skatowhere it begins or ends a @syntax{sequence_of_statements}. 53043561Skato@cindex Blank lines (in an @code{if} statement) 53143561Skato 53243561Skato@smallexample @c adanocomment 53343561Skato@group 53443561Skato A := 5; 53543561Skato 53643561Skato if A = 5 then 53743561Skato null; 53843561Skato end if; 53943561Skato 54043561Skato A := 6; 54143561Skato@end group 54243561Skato@end smallexample 54343561Skato@end itemize 54443561Skato 54543561Skato@subsection Case Statements 54643561Skato@cindex @code{case} statements 54743561Skato 54843561Skato@itemize @bullet 54943561Skato@item 55043561SkatoLayout is as below. For long @code{case} statements, the extra indentation 55143561Skatocan be saved by aligning the @code{when} clauses with the opening @code{case}. 55243561Skato 55343561Skato@smallexample @c adanocomment 55443561Skato@group 55543561Skato case @var{expression} is 55643561Skato when @var{condition} => 55743561Skato ... 55843561Skato when @var{condition} => 55943561Skato ... 56043561Skato end case; 56143561Skato@end group 56243561Skato@end smallexample 56343561Skato@end itemize 56443561Skato 56543561Skato@subsection Loop Statements 56643561Skato@cindex Loop statements 56743561Skato 56843561Skato@itemize @bullet 56943561Skato@item 57043561SkatoWhen possible, have @code{for} or @code{while} on one line with the 57143561Skatocondition and the @code{loop} keyword. 57243561Skato 57343561Skato@smallexample @c adanocomment 57443561Skato@group 57543561Skato for J in S'Range loop 57643561Skato ... 57743561Skato end loop; 57843561Skato@end group 57943561Skato@end smallexample 58043561Skato 58143561Skato@noindent 58243561SkatoIf the condition is too long, split the condition (see ``If 58343561Skatostatements'' above) and align @code{loop} with the @code{for} or 58443561Skato@code{while} keyword. 58543561Skato@cindex Alignment (in a loop statement) 58643561Skato 58743561Skato@smallexample @c adanocomment 58843561Skato@group 58943561Skato while @var{long_condition_that_has_to_be_split} 59043561Skato and then @var{continued_on_the_next_line} 59143561Skato loop 59243561Skato ... 59343561Skato end loop; 59443561Skato@end group 59543561Skato@end smallexample 59643561Skato 59743561Skato@noindent 59843561SkatoIf the @syntax{loop_statement} has an identifier, it is laid out as follows: 59943561Skato 60043561Skato@smallexample @c adanocomment 60143561Skato@group 60243561Skato Outer : while not @var{condition} loop 60343561Skato ... 60443561Skato end Outer; 60543561Skato@end group 60643561Skato@end smallexample 60743561Skato@end itemize 60843561Skato 60943561Skato@subsection Block Statements 61043561Skato@cindex Block statement 61143561Skato 61243561Skato@itemize @bullet 61343561Skato@item 61443561SkatoThe @code{declare} (optional), @code{begin} and @code{end} words 61543561Skatoare aligned, except when the @syntax{block_statement} is named. There 61643561Skatois a blank line before the @code{begin} keyword: 61743561Skato@cindex Alignment (in a block statement) 61843561Skato 61943561Skato@smallexample @c adanocomment 62043561Skato@group 62143561Skato Some_Block : declare 62243561Skato ... 62343561Skato 62443561Skato begin 62543561Skato ... 62643561Skato end Some_Block; 62743561Skato@end group 62843561Skato@end smallexample 62943561Skato 63043561Skato@end itemize 63143561Skato 63243561Skato@c ------------------------------------------------------------------------- 63343561Skato@node Subprograms, Packages, Statements, Top 63443561Skato@section Subprograms 63543561Skato@c ------------------------------------------------------------------------- 63643561Skato@cindex Subprograms 63743561Skato 63843561Skato@subsection Subprogram Declarations 63943561Skato@c ------------------------------------------------------------------------- 64043561Skato@itemize @bullet 64143561Skato 64243561Skato@item 64343561SkatoDo not write the @code{in} for parameters. 64443561Skato 64543561Skato@smallexample @c adanocomment 64643561Skato function Length (S : String) return Integer; 64743561Skato@end smallexample 64843561Skato 64943561Skato@item 65043561SkatoWhen the declaration line for a procedure or a function is too long to fit 65143561Skatothe entire declaration (including the keyword procedure or function) on a 65243561Skatosingle line, then fold it, putting a single parameter on a line, aligning 65343561Skatothe colons, as in: 65443561Skato 65543561Skato@smallexample @c adanocomment 65643561Skato@group 65743561Skato procedure Set_Heading 65843561Skato (Source : String; 65943561Skato Count : Natural; 66043561Skato Pad : Character := Space; 66143561Skato Fill : Boolean := True); 66243561Skato@end group 66343561Skato@end smallexample 66443561Skato 66543561Skato@noindent 66643561SkatoIn the case of a function, if the entire spec does not fit on one line, then 66743561Skatothe return may appear after the last parameter, as in: 66843561Skato 66943561Skato@smallexample @c adanocomment 67043561Skato@group 67143561Skato function Head 67243561Skato (Source : String; 67343561Skato Count : Natural; 67443561Skato Pad : Character := Space) return String; 67543561Skato@end group 67643561Skato@end smallexample 67743561Skato 67843561Skato@noindent 67943561SkatoOr it may appear on its own as a separate line. This form is preferred when 68043561Skatoputting the return on the same line as the last parameter would result in 68143561Skatoan overlong line. The return type may optionally be aligned with the types 68243561Skatoof the parameters (usually we do this aligning if it results only in a small 68343561Skatonumber of extra spaces, and otherwise we don't attempt to align). So two 68443561Skatoalternative forms for the above spec are: 68543561Skato 68643561Skato@smallexample @c adanocomment 68743561Skato@group 68843561Skato function Head 68943561Skato (Source : String; 69043561Skato Count : Natural; 69143561Skato Pad : Character := Space) 69243561Skato return String; 69343561Skato 69443561Skato function Head 69543561Skato (Source : String; 69643561Skato Count : Natural; 69743561Skato Pad : Character := Space) 69843561Skato return String; 69943561Skato@end group 70043561Skato@end smallexample 70143561Skato 70243561Skato@end itemize 70343561Skato 70443561Skato@subsection Subprogram Bodies 70543561Skato@c ------------------------------------------------------------------------- 70643561Skato@cindex Subprogram bodies 70743561Skato 70843561Skato@itemize @bullet 70943561Skato@item 71043561SkatoFunction and procedure bodies should usually be sorted alphabetically. Do 71143561Skatonot attempt to sort them in some logical order by functionality. For a 71243561Skatosequence of subprogram specs, a general alphabetical sorting is also 71343561Skatousually appropriate, but occasionally it makes sense to group by major 71443561Skatofunction, with appropriate headers. 71543561Skato 71643561Skato@item 71743561SkatoAll subprograms have a header giving the function name, with the following 71843561Skatoformat: 71943561Skato 72043561Skato@smallexample @c adanocomment 72143561Skato@group 72243561Skato ----------------- 72343561Skato -- My_Function -- 72443561Skato ----------------- 72543561Skato 72643561Skato procedure My_Function is 72743561Skato begin 72843561Skato ... 72943561Skato end My_Function; 73043561Skato@end group 73143561Skato@end smallexample 73243561Skato 73343561Skato@noindent 73443561SkatoNote that the name in the header is preceded by a single space, 73543561Skatonot two spaces as for other comments. These headers are used on 73643561Skatonested subprograms as well as outer level subprograms. They may 73743561Skatoalso be used as headers for sections of comments, or collections 73843561Skatoof declarations that are related. 73943561Skato 74043561Skato@item 74143561SkatoEvery subprogram body must have a preceding @syntax{subprogram_declaration}, 74243561Skatowhich includes proper client documentation so that you do not need to 74343561Skatoread the subprogram body in order to understand what the subprogram does and 74443561Skatohow to call it. All subprograms should be documented, without exceptions. 74543561Skato 74643561Skato@item 74743561Skato@cindex Blank lines (in subprogram bodies) 74843561SkatoA sequence of declarations may optionally be separated from the following 74943561Skatobegin by a blank line. Just as we optionally allow blank lines in general 75043561Skatobetween declarations, this blank line should be present only if it improves 75143561Skatoreadability. Generally we avoid this blank line if the declarative part is 75243561Skatosmall (one or two lines) and the body has no blank lines, and we include it 75343561Skatoif the declarative part is long or if the body has blank lines. 75443561Skato 75543561Skato@item 75643561SkatoIf the declarations in a subprogram contain at least one nested 75743561Skatosubprogram body, then just before the @code{begin} of the enclosing 75843561Skatosubprogram, there is a comment line and a blank line: 75943561Skato 76043561Skato@smallexample @c adanocomment 76143561Skato@group 76243561Skato -- Start of processing for @var{Enclosing_Subprogram} 76343561Skato 76443561Skato begin 76543561Skato ... 76643561Skato end @var{Enclosing_Subprogram}; 76743561Skato@end group 76843561Skato@end smallexample 76943561Skato 77043561Skato@item 77143561SkatoWhen nested subprograms are present, variables that are referenced by any 77243561Skatonested subprogram should precede the nested subprogram specs. For variables 77343561Skatothat are not referenced by nested procedures, the declarations can either also 77443561Skatobe before any of the nested subprogram specs (this is the old style, more 77543561Skatogenerally used). Or then can come just before the begin, with a header. The 77643561Skatofollowing example shows the two possible styles: 77743561Skato 77843561Skato@smallexample @c adanocomment 77943561Skato@group 78043561Skato procedure Style1 is 78143561Skato Var_Referenced_In_Nested : Integer; 78243561Skato Var_Referenced_Only_In_Style1 : Integer; 78343561Skato 78443561Skato proc Nested; 78543561Skato -- Comments ... 78643561Skato 78743561Skato 78843561Skato ------------ 78943561Skato -- Nested -- 79043561Skato ------------ 79143561Skato 79243561Skato procedure Nested is 79343561Skato begin 79443561Skato ... 79543561Skato end Nested; 79643561Skato 79743561Skato -- Start of processing for Style1 79843561Skato 79943561Skato begin 80043561Skato ... 80143561Skato end Style1; 80243561Skato 80343561Skato@end group 80443561Skato 80543561Skato@group 80643561Skato procedure Style2 is 80743561Skato Var_Referenced_In_Nested : Integer; 80843561Skato 80943561Skato proc Nested; 81043561Skato -- Comments ... 81143561Skato 81243561Skato ------------ 81343561Skato -- Nested -- 81443561Skato ------------ 81543561Skato 81643561Skato procedure Nested is 81743561Skato begin 81843561Skato ... 81943561Skato end Nested; 82043561Skato 82143561Skato -- Local variables 82243561Skato 82343561Skato Var_Referenced_Only_In_Style2 : Integer; 82443561Skato 82543561Skato -- Start of processing for Style2 82643561Skato 82743561Skato begin 82843561Skato ... 82943561Skato end Style2; 83043561Skato 83143561Skato@end group 83243561Skato@end smallexample 83343561Skato 83443561Skato@noindent 83543561SkatoFor new code, we generally prefer Style2, but we do not insist on 83643561Skatomodifying all legacy occurrences of Style1, which is still much 83743561Skatomore common in the sources. 83843561Skato 83943561Skato@end itemize 84043561Skato 84143561Skato 84243561Skato@c ------------------------------------------------------------------------- 84343561Skato@node Packages, Program Structure, Subprograms, Top 84443561Skato@section Packages and Visibility Rules 84543561Skato@c ------------------------------------------------------------------------- 84643561Skato@cindex Packages 84743561Skato 84843561Skato@itemize @bullet 84943561Skato@item 85043561SkatoAll program units and subprograms have their name at the end: 85143561Skato 85243561Skato@smallexample @c adanocomment 85343561Skato@group 85443561Skato package P is 85543561Skato ... 85643561Skato end P; 85743561Skato@end group 85843561Skato@end smallexample 85943561Skato 86043561Skato@item 86143561SkatoWe will use the style of @code{use}-ing @code{with}-ed packages, with 86243561Skatothe context clauses looking like: 86343561Skato@cindex @code{use} clauses 86443561Skato 86543561Skato@smallexample @c adanocomment 86643561Skato@group 86743561Skato with A; use A; 86843561Skato with B; use B; 86943561Skato@end group 87043561Skato@end smallexample 87143561Skato 87243561Skato@item 87343561SkatoNames declared in the visible part of packages should be 87443561Skatounique, to prevent name clashes when the packages are @code{use}d. 87543561Skato@cindex Name clash avoidance 87643561Skato 87743561Skato@smallexample @c adanocomment 87843561Skato@group 87943561Skato package Entity is 88043561Skato type Entity_Kind is ...; 88143561Skato ... 88243561Skato end Entity; 88343561Skato@end group 88443561Skato@end smallexample 88543561Skato 88643561Skato@item 88743561SkatoAfter the file header comment, the context clause and unit specification 88843561Skatoshould be the first thing in a @syntax{program_unit}. 88943561Skato 89043561Skato@item 89143561SkatoPreelaborate, Pure and Elaborate_Body pragmas should be added right after the 89243561Skatopackage name, indented an extra level and using the parameterless form: 89343561Skato 89443561Skato@smallexample @c adanocomment 89543561Skato@group 89643561Skato package Preelaborate_Package is 89743561Skato pragma Preelaborate; 89843561Skato ... 89943561Skato end Preelaborate_Package; 90043561Skato@end group 90143561Skato@end smallexample 90243561Skato 90343561Skato@end itemize 90443561Skato 90543561Skato@c ------------------------------------------------------------------------- 90643561Skato@node Program Structure, GNU Free Documentation License, Packages, Top 90743561Skato@section Program Structure and Compilation Issues 90843561Skato@c ------------------------------------------------------------------------- 90943561Skato@cindex Program structure 91043561Skato 91143561Skato@itemize @bullet 91243561Skato@item 91343561SkatoEvery GNAT source file must be compiled with the @option{-gnatg} 91443561Skatoswitch to check the coding style. 91543561Skato(Note that you should look at 91643561Skato@file{style.adb} to see the lexical rules enforced by 91743561Skato@option{-gnatg}). 91843561Skato@cindex @option{-gnatg} option (to gcc) 91943561Skato@cindex @file{style.adb} file 92043561Skato 92143561Skato@item 92243561SkatoEach source file should contain only one compilation unit. 92343561Skato 92443561Skato@item 92543561SkatoFilenames should be 8 or fewer characters, followed by the @code{.adb} 92643561Skatoextension for a body or @code{.ads} for a spec. 92743561Skato@cindex File name length 92843561Skato 92943561Skato@item 93043561SkatoUnit names should be distinct when ``krunch''ed to 8 characters 93143561Skato(see @file{krunch.ads}) and the filenames should match the unit name, 93243561Skatoexcept that they are all lower case. 93343561Skato@cindex @file{krunch.ads} file 93443561Skato@end itemize 93543561Skato 93643561Skato 93743561Skato@c ********************************** 93843561Skato@c * GNU Free Documentation License * 93943561Skato@c ********************************** 94043561Skato@include fdl.texi 94143561Skato@c GNU Free Documentation License 94243561Skato@cindex GNU Free Documentation License 94343561Skato 94443561Skato@node Index,,GNU Free Documentation License, Top 94543561Skato@unnumberedsec Index 94643561Skato 94743561Skato@printindex cp 94843561Skato 94943561Skato@contents 95043561Skato 95143561Skato@bye 95243561Skato