gnat-style.texi

来自「理解和实践操作系统的一本好书」· TEXI 代码 · 共 949 行 · 第 1/2 页

\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                     Copyright (C) 1992-2007, AdaCore                       o
@c                                                                            o
@c  GNAT is free software;  you can  redistribute it  and/or modify it under  o
@c  terms of the  GNU General Public License as published  by the Free Soft-  o
@c  ware  Foundation;  either version 2,  or (at your option) any later ver-  o
@c  sion.  GNAT is distributed in the hope that it will be useful, but WITH-  o
@c  OUT ANY WARRANTY;  without even the  implied warranty of MERCHANTABILITY  o
@c  or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License  o
@c  for  more details.  You should have  received  a copy of the GNU General  o
@c  Public License  distributed with GNAT;  see file COPYING.  If not, write  o
@c  to  the  Free Software Foundation,  51  Franklin  Street,  Fifth  Floor,  o
@c  Boston, MA 02110-1301, USA.                                               o
@c                                                                            o
@c oooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooo

@setfilename gnat-style.info

@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

Copyright @copyright{} 1995-2007, Free Software Foundation

Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.1
or any later version published by the Free Software Foundation;
with the Invariant Sections being ``GNU Free Documentation License'', with the
Front-Cover Texts being
``GNAT Coding Style'' and ``A Guide for GNAT Developers'',
and with no Back-Cover Texts.
A copy of the license is included in the section entitled
``GNU Free Documentation License''.
@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
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.1
or any later version published by the Free Software Foundation;
with the Invariant Sections being ``GNU Free Documentation License'', with the
Front-Cover Texts being
``GNAT Coding Style'' and ``A Guide for GNAT Developers''
and with no Back-Cover Texts.
A copy of the license is included in the section entitled
``GNU Free Documentation License''.
@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
       ...