gcc/ada/gnat-style.texi

   1 \input texinfo   @c -*-texinfo-*-
   2 @c %**start of header
   3
   4 @c oooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooo
   5 @c                                                                            o
   6 @c                           GNAT DOCUMENTATION                               o
   7 @c                                                                            o
   8 @c                      G N A T   C O D I N G   S T Y L E                     o
   9 @c                                                                            o
  10 @c                                                                            o
  11 @c          Copyright (C) 1992-2001 Ada Core Technologies, Inc.               o
  12 @c                                                                            o
  13 @c  GNAT is free software;  you can  redistribute it  and/or modify it under  o
  14 @c  terms of the  GNU General Public License as published  by the Free Soft-  o
  15 @c  ware  Foundation;  either version 2,  or (at your option) any later ver-  o
  16 @c  sion.  GNAT is distributed in the hope that it will be useful, but WITH-  o
  17 @c  OUT ANY WARRANTY;  without even the  implied warranty of MERCHANTABILITY  o
  18 @c  or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License  o
  19 @c  for  more details.  You should have  received  a copy of the GNU General  o
  20 @c  Public License  distributed with GNAT;  see file COPYING.  If not, write  o
  21 @c  to  the Free Software Foundation,  59 Temple Place - Suite 330,  Boston,  o
  22 @c  MA 02111-1307, USA.                                                       o
  23 @c                                                                            o
  24 @c oooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooo
  25
  26 @setfilename gnat-style.info
  27 @settitle GNAT Coding Style
  28 @dircategory Programming
  29 @direntry
  30 * gnat-style: (gnat-style).      GNAT Coding Style
  31 @end direntry
  32
  33 @macro syntax{element}
  34 @t{\element\}
  35 @end macro
  36 @c %**end of header
  37
  38 @ifinfo
  39      @center GNAT Coding Style
  40
  41      @center A guide for GNAT developers
  42      Copyright (C) 1992-2001 Ada Core Technologies, Inc.
  43 @end ifinfo
  44
  45 @titlepage
  46 @sp 10
  47 @title GNAT Coding Style
  48 @subtitle A guide for GNAT developers
  49 @author Ada Core Technologies, Inc.
  50 @end titlepage
  51 @raisesections
  52
  53 @node    Top,       General,         , (dir)
  54 @comment node-name, next,    previous, up
  55
  56 @menu
  57 * General::
  58 * Lexical Elements::
  59 * Declarations and Types::
  60 * Expressions and Names::
  61 * Statements::
  62 * Subprograms::
  63 * Packages::
  64 * Program Structure::
  65 @end menu
  66
  67 @c  -------------------------------------------------------------------------
  68 @node    General, Lexical Elements, Top, Top
  69 @section General
  70 @c  -------------------------------------------------------------------------
  71
  72 @noindent
  73 Most of GNAT is written in Ada using a consistent style to ensure
  74 readability of the code.  This document has been written to help
  75 maintain this consistent style, while having a large group of developers
  76 work on the compiler.
  77
  78 @noindent
  79 For the coding style in the C parts of the compiler and run time,
  80 see the GNU Coding Guidelines.
  81
  82 @noindent
  83 This document is structured after the Ada Reference manual.
  84 Those familiar with that document should be able to quickly
  85 lookup style rules for particular constructs.
  86
  87 @c  -------------------------------------------------------------------------
  88 @node    Lexical Elements, Declarations and Types, General, Top
  89 @section Lexical Elements
  90 @c  -------------------------------------------------------------------------
  91
  92 @subsection Character Set and Separators
  93 @c  -------------------------------------------------------------------------
  94
  95 @itemize @bullet
  96 @item
  97 The character set used should be plain 7-bit ASCII@.
  98 The only separators allowed are space and the end-of-line sequence.
  99 No other control character or format effector (such as HT, VT, FF)
 100 should be used.
 101 The normal end-of-line sequence is used, which may be LF, CR/LF or CR,
 102 depending on the host system.  An optional SUB (16#1A#) may be present as the
 103 last character in the file on hosts using that character as file terminator.
 104
 105 @item
 106 Files that are checked in or distributed should be in host format.
 107
 108 @item
 109 A line should never be longer than 79 characters, not counting the line
 110 separator.
 111
 112 @item
 113 Lines must not have trailing blanks.
 114
 115 @item
 116 Indentation is 3 characters per level for if statements, loops, case
 117 statements.  For exact information on required spacing between lexical
 118 elements, see file @file{style.adb}.
 119
 120 @end itemize
 121
 122 @subsection Identifiers
 123 @c  -------------------------------------------------------------------------
 124 @itemize @bullet
 125 @item
 126 Identifiers will start with an upper case letter, and each letter following
 127 an underscore will be upper case.  Short acronyms may be all upper case.
 128 All other letters are lower case.
 129 An exception is for identifiers matching a foreign language.  In particular,
 130 we use all lower case where appropriate for C@.
 131
 132 @item
 133 Use underscores to separate words in an identifier.
 134
 135 @item Try to limit your use of abbreviations in identifiers.
 136 It is ok to make a few abbreviations, explain what they mean, and then
 137 use them frequently, but don't use lots of obscure abbreviations.  An
 138 example is the @code{ALI} word which stands for Ada Library
 139 Information and is by convention always written in upper-case when
 140 used in entity names.
 141
 142 @smallexample
 143        procedure Find_ALI_Files;
 144 @end smallexample
 145
 146 @item
 147 Don't use the variable @samp{I}, use @samp{J} instead, @samp{I} is too
 148 easily mixed up with @samp{1} in some fonts.  Similarly don't use the
 149 variable @samp{O}, which is too easily mixed up with the number @samp{0}.
 150 @end itemize
 151
 152 @subsection Numeric Literals
 153 @c  -------------------------------------------------------------------------
 154 @itemize @bullet
 155 @item
 156 Numeric literals should include underscores where helpful for
 157 readability.
 158
 159 @smallexample
 160       1_000_000
 161       16#8000_000#
 162       3.14159_26535_89793_23846
 163 @end smallexample
 164 @end itemize
 165
 166 @subsection Reserved Words
 167 @c  -------------------------------------------------------------------------
 168 @itemize @bullet
 169 @item
 170 Reserved words use all lower case.
 171
 172 @smallexample
 173        return else
 174 @end smallexample
 175
 176 @item
 177 The words @samp{Access}, @samp{Delta} and @samp{Digits} are
 178 capitalized when used as @syntax{attribute_designator}.
 179 @end itemize
 180
 181 @subsection Comments
 182 @c  -------------------------------------------------------------------------
 183
 184 @itemize @bullet
 185 @item
 186 Comment start with @samp{--  } (i.e.@: @samp{--} followed by two spaces).
 187 The only exception to this rule (i.e.@: one space is tolerated) is when the
 188 comment ends with @samp{ --}.
 189 It also accepted to have only one space between @samp{--} and the start
 190 of the comment when the comment is at the end of a line,
 191 after some Ada code.
 192
 193 @item
 194 Every sentence in a comment should start with an upper-case letter (including
 195 the first letter of the comment).
 196
 197 @item
 198 When declarations are commented with ``hanging'' comments, i.e.@:
 199 comments after the declaration, there is no blank line before the
 200 comment, and if it is absolutely necessary to have blank lines within
 201 the comments these blank lines @emph{do} have a @samp{--} (unlike the
 202 normal rule, which is to use entirely blank lines for separating
 203 comment paragraphs).  The comment start at same level of indentation
 204 as code they are commenting.
 205
 206 @smallexample
 207        z : Integer;
 208        --  @r{Integer value for storing value of} z
 209        --
 210        --  @r{The previous line was a blank line.}
 211 @end smallexample
 212
 213 @item
 214 Comments that are dubious or incomplete or comment on possibly
 215 wrong or incomplete code should be preceded or followed by @samp{???}@.
 216
 217 @item
 218 Comments in a subprogram body must generally be surrounded by blank lines,
 219 except after a @samp{begin}:
 220
 221 @smallexample
 222        begin
 223           --  @r{Comment for the next statement}
 224
 225           A := 5;
 226
 227           --  @r{Comment for the B statement}
 228
 229           B := 6;
 230 @end smallexample
 231
 232 @item
 233 In sequences of statements, comments at the end of the lines should be
 234 aligned.
 235
 236 @smallexample
 237         My_Identifier := 5;      --  @r{First comment}
 238         Other_Id := 6;           --  @r{Second comment}
 239 @end smallexample
 240
 241 @item
 242 Short comments that fit on a single line are @emph{not} ended with a
 243 period.  Comments taking more than a line are punctuated in the normal
 244 manner.
 245
 246 @item
 247 Comments should focus on why instead of what.
 248 Descriptions of what subprograms do go with the specification.
 249
 250 @item
 251 Comments describing a subprogram spec should specifically mention the
 252 formal argument names.  General rule: write a comment that does not
 253 depend on the names of things.  The names are supplementary, not
 254 sufficient, as comments.
 255
 256 @item
 257 Do NOT put two spaces after periods in comments.
 258 @end itemize
 259
 260 @c  -------------------------------------------------------------------------
 261 @node    Declarations and Types, Expressions and Names, Lexical Elements,Top
 262 @section Declarations and Types
 263 @c  -------------------------------------------------------------------------
 264
 265 @itemize @bullet
 266 @item
 267 In entity declarations, colons must be surrounded by spaces.  Colons
 268 should be aligned.
 269
 270 @smallexample
 271         Entity1   : Integer;
 272         My_Entity : Integer;
 273 @end smallexample
 274
 275 @item
 276 Declarations should be grouped in a logical order.
 277 Related groups of declarations may be preceded by a header comment.
 278
 279 @item
 280 All local subprograms in a subprogram or package body should be declared
 281 before the first local subprogram body.
 282
 283 @item
 284 Don't declare local entities that hide global entities.
 285
 286 @item
 287 Don't declare multiple variables in one declaration that spans lines.
 288 Start a new declaration on each line, instead.
 289
 290 @item
 291 The @syntax{defining_identifier}s of global declarations serve as
 292 comments of a sort.  So don't choose terse names, but look for names
 293 that give useful information instead.
 294
 295 @item
 296 Local names can be shorter, because they are used only within
 297 one context, where comments explain their purpose.
 298
 299 @end itemize
 300
 301
 302 @c  -------------------------------------------------------------------------
 303 @node    Expressions and Names, Statements, Declarations and Types, Top
 304 @section Expressions and Names
 305 @c  -------------------------------------------------------------------------
 306
 307 @itemize @bullet
 308
 309 @item
 310 Every operator must be surrounded by spaces, except for the
 311 exponentiation operator.
 312
 313 @smallexample
 314        E := A * B**2 + 3 * (C - D);
 315 @end smallexample
 316
 317 @item
 318 When folding a long line, fold before an operator, not after.
 319
 320 @item
 321 Use parentheses where they clarify the intended association of operands
 322 with operators:
 323 @smallexample
 324        (A / B) * C
 325 @end smallexample
 326 @end itemize
 327
 328 @c  -------------------------------------------------------------------------
 329 @node    Statements, Subprograms, Expressions and Names, Top
 330 @section Statements
 331 @c  -------------------------------------------------------------------------
 332
 333 @subsection Simple and Compound Statements
 334 @c  -------------------------------------------------------------------------
 335 @itemize @bullet
 336 @item
 337 Use only one statement or label per line.
 338 @item
 339 A longer @syntax{sequence_of_statements} may be divided in logical
 340 groups or separated from surrounding code using a blank line.
 341 @end itemize
 342
 343 @subsection If Statements
 344 @c  -------------------------------------------------------------------------
 345 @itemize @bullet
 346 @item
 347 When the @samp{if}, @samp{elsif} or @samp{else} keywords fit on the
 348 same line with the condition and the @samp{then} keyword, then the
 349 statement is formatted as follows:
 350
 351 @smallexample
 352         if @var{condition} then
 353            ...
 354         elsif @var{condition} then
 355            ...
 356         else
 357            ...
 358         end if;
 359 @end smallexample
 360
 361 @noindent
 362 When the above layout is not possible, @samp{then} should be aligned
 363 with @samp{if}, and conditions should preferably be split before an
 364 @samp{and} or @samp{or} keyword a follows:
 365
 366 @smallexample
 367         if @var{long_condition_that_has_to_be_split}
 368           and then @var{continued_on_the_next_line}
 369         then
 370            ...
 371         end if;
 372 @end smallexample
 373
 374 @noindent
 375 The @samp{elsif}, @samp{else} and @samp{end if} always line up with
 376 the @samp{if} keyword.  The preferred location for splitting the line
 377 is before @samp{and} or @samp{or}.  The continuation of a condition is
 378 indented with two spaces or as many as needed to make nesting clear.
 379 As exception, if conditions are closely related either of the
 380 following is allowed:
 381
 382 @smallexample
 383      if x = lakdsjfhlkashfdlkflkdsalkhfsalkdhflkjdsahf
 384           or else
 385         x = asldkjhalkdsjfhhfd
 386           or else
 387         x = asdfadsfadsf
 388      then
 389
 390      if x = lakdsjfhlkashfdlkflkdsalkhfsalkdhflkjdsahf or else
 391         x = asldkjhalkdsjfhhfd                         or else
 392         x = asdfadsfadsf
 393      then
 394 @end smallexample
 395
 396 @item
 397 Conditions should use short-circuit forms (@samp{and then},
 398 @samp{or else}).
 399
 400 @item
 401 Complex conditions in if statements are indented two characters:
 402
 403 @smallexample
 404       if @var{this_complex_condition}
 405         and then @var{that_other_one}
 406         and then @var{one_last_one}
 407       then
 408          ...
 409 @end smallexample
 410
 411 @item
 412 Every @samp{if} block is preceded and followed by a blank line, except
 413 where it begins or ends a @syntax{sequence_of_statements}.
 414
 415 @smallexample
 416         A := 5;
 417
 418         if A = 5 then
 419            null;
 420         end if;
 421
 422         A := 6;
 423 @end smallexample
 424 @end itemize
 425
 426 @subsection Case Statements
 427 @itemize @bullet
 428
 429 @item
 430 Layout is as below.  For long case statements, the extra indentation
 431 can be saved by aligning the when clauses with the opening case.
 432
 433 @smallexample
 434        case @var{expression} is
 435           when @var{condition} =>
 436              ...
 437           when @var{condition} =>
 438              ...
 439        end case;
 440 @end smallexample
 441 @end itemize
 442
 443 @subsection Loop Statements
 444 @itemize @bullet
 445
 446 @noindent
 447 When possible, have @samp{for} or @samp{while} on one line with the
 448 condition and the @samp{loop} keyword.
 449
 450 @smallexample
 451        for J in S'Range loop
 452           ...
 453        end loop;
 454 @end smallexample
 455
 456 @noindent
 457 If the condition is too long, split the condition (see ``If
 458 statements'' above) and align @samp{loop} with the @samp{for} or
 459 @samp{while} keyword.
 460
 461 @smallexample
 462       while @var{long_condition_that_has_to_be_split}
 463         and then @var{continued_on_the_next_line}
 464       loop
 465          ...
 466       end loop;
 467 @end smallexample
 468
 469 @noindent
 470 If the @syntax{loop_statement} has an identifier, it is laid out as follows:
 471
 472 @smallexample
 473       Outer : while not @var{condition} loop
 474          ...
 475       end Outer;
 476 @end smallexample
 477 @end itemize
 478
 479 @subsection Block Statements
 480 @itemize @bullet
 481
 482 @item
 483 The @samp{declare} (optional), @samp{begin} and @samp{end} statements
 484 are aligned, except when the @syntax{block_statement} is named.  There
 485 is a blank line before the @samp{begin} keyword:
 486
 487 @smallexample
 488       Some_Block : declare
 489          ...
 490
 491       begin
 492          ...
 493       end Some_Block;
 494 @end smallexample
 495
 496 @end itemize
 497
 498 @c  -------------------------------------------------------------------------
 499 @node    Subprograms, Packages, Statements, Top
 500 @section Subprograms
 501 @c  -------------------------------------------------------------------------
 502
 503
 504 @subsection Subprogram Declarations
 505 @c  -------------------------------------------------------------------------
 506 @itemize @bullet
 507
 508 @item
 509 Do not write the @samp{in} for parameters, especially in functions:
 510
 511 @smallexample
 512       function Length (S : String) return Integer;
 513 @end smallexample
 514
 515 @item
 516 When the declaration line for a procedure or a function is too long, fold it.
 517 In this case, align the colons, and, for functions, the result type.
 518
 519 @smallexample
 520       function Head
 521         (Source : String;
 522          Count  : Natural;
 523          Pad    : Character := Space)
 524          return   String;
 525 @end smallexample
 526
 527 @item
 528 The parameter list for a subprogram is preceded by a space:
 529
 530 @smallexample
 531         procedure Func (A : Integer);
 532 @end smallexample
 533
 534 @end itemize
 535
 536 @subsection Subprogram Bodies
 537 @c  -------------------------------------------------------------------------
 538 @itemize @bullet
 539
 540 @item
 541 The functions and procedures should always be sorted alphabetically in
 542 a compilation unit.
 543
 544 @item
 545 All subprograms have a header giving the function name, with the following
 546 format:
 547
 548 @smallexample
 549       -----------------
 550       -- My_Function --
 551       -----------------
 552
 553       procedure My_Function is
 554       begin
 555 @end smallexample
 556
 557 Note that the name in the header is preceded by a single space,
 558 not two spaces as for other comments.
 559
 560 @item
 561 Every subprogram body must have a preceding @syntax{subprogram_declaration}.
 562
 563 @item
 564 If there any declarations in a subprogram, the @samp{begin} keyword is
 565 preceded by a blank line.
 566
 567 @item
 568 If the declarations in a subprogram contain at least one nested
 569 subprogram body, then just before the @samp{begin} of the enclosing
 570 subprogram, there is a line:
 571
 572 @smallexample
 573         --  @r{Start of processing for @var{Enclosing_Subprogram}}
 574
 575         begin
 576 @end smallexample
 577
 578 @end itemize
 579
 580 @c  -------------------------------------------------------------------------
 581 @node    Packages, Program Structure, Subprograms, Top
 582 @section Packages and Visibility Rules
 583 @c  -------------------------------------------------------------------------
 584
 585 @itemize @bullet
 586
 587 @item
 588 All program units and subprograms have their name at the end:
 589
 590 @smallexample
 591       package P is
 592          ...
 593       end P;
 594 @end smallexample
 595
 596 @item
 597 We will use the style of @samp{use}-ing @samp{with}-ed packages, with
 598 the context clauses looking like:
 599
 600 @smallexample
 601       with A; use A;
 602       with B; use B;
 603 @end smallexample
 604
 605 @item
 606 Names declared in the visible part of packages should be
 607 unique, to prevent name clashes when the packages are @samp{use}d.
 608
 609 @smallexample
 610       package Entity is
 611          type Entity_Kind is ...;
 612          ...
 613       end Entity;
 614 @end smallexample
 615
 616 @item
 617 After the file header comment, the context clause and unit specification
 618 should be the first thing in a @syntax{program_unit}.
 619 @end itemize
 620
 621 @c  -------------------------------------------------------------------------
 622 @node    Program Structure,, Packages, Top
 623 @section Program Structure and Compilation Issues
 624 @c  -------------------------------------------------------------------------
 625
 626 @itemize @bullet
 627 @item
 628 Every GNAT source file must be compiled with the @option{-gnatg}
 629 switch to check the coding style (Note that you should look at
 630 @file{style.adb} to see the lexical rules enforced by
 631 @option{-gnatg}).
 632
 633 @item
 634 Each source file should contain only one compilation unit.
 635
 636 @item
 637 Filenames should be 8 characters or less followed by the @samp{.adb}
 638 extension for a body or @samp{.ads} for a spec.
 639
 640 @item
 641 Unit names should be distinct when krunched to 8 characters
 642 (see @file{krunch.ads}) and the filenames should match the unit name,
 643 except that they are all lower case.
 644 @end itemize
 645
 646 @bye