gcc/ada/gnat-style.texi

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