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 Copyright (C) 1992-2004 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 27@settitle GNAT Coding Style 28@setchapternewpage odd 29 30 31@dircategory Programming 32@direntry 33* gnat-style: (gnat-style). GNAT Coding Style 34@end direntry 35 36@macro syntax{element} 37@t{\element\} 38@end macro 39@c %**end of header 40 41@titlepage 42@sp 10 43@title GNAT Coding Style 44@flushright 45@titlefont{A Guide for GNAT Developers} 46@end flushright 47@sp 2 48@subtitle GNAT, The GNU Ada 95 Compiler 49 50@author Ada Core Technologies, Inc. 51 52@page 53@vskip 0pt plus 1filll 54 55Copyright @copyright{} 1995-2003, Free Software Foundation 56 57Permission is granted to copy, distribute and/or modify this document 58under the terms of the GNU Free Documentation License, Version 1.1 59or any later version published by the Free Software Foundation; 60with the Invariant Sections being ``GNU Free Documentation License'', with the 61Front-Cover Texts being 62``GNAT Coding Style'' and ``A Guide for GNAT Developers'', 63and with no Back-Cover Texts. 64A copy of the license is included in the section entitled 65``GNU Free Documentation License''. 66@end titlepage 67 68@raisesections 69 70@node Top, General, , (dir) 71@comment node-name, next, previous, up 72 73@ifnottex 74@noindent 75GNAT Coding Style@* 76A Guide for GNAT Developers 77@sp 2 78@noindent 79GNAT, The GNU Ada 95 Compiler@* 80 81@noindent 82Permission is granted to copy, distribute and/or modify this document 83under the terms of the GNU Free Documentation License, Version 1.1 84or any later version published by the Free Software Foundation; 85with the Invariant Sections being ``GNU Free Documentation License'', with the 86Front-Cover Texts being 87``GNAT Coding Style'' and ``A Guide for GNAT Developers'' 88and with no Back-Cover Texts. 89A copy of the license is included in the section entitled 90``GNU Free Documentation License''. 91@end ifnottex 92 93 94@menu 95* General:: 96* Lexical Elements:: 97* Declarations and Types:: 98* Expressions and Names:: 99* Statements:: 100* Subprograms:: 101* Packages:: 102* Program Structure:: 103* GNU Free Documentation License:: 104* Index:: 105@end menu 106 107@c ------------------------------------------------------------------------- 108@node General, Lexical Elements, Top, Top 109@section General 110@c ------------------------------------------------------------------------- 111 112@noindent 113Most of GNAT is written in Ada using a consistent style to ensure 114readability of the code. This document has been written to help 115maintain this consistent style, while having a large group of developers 116work on the compiler. 117 118For the coding style in the C parts of the compiler and run time, 119see the GNU Coding Guidelines. 120 121This document is structured after the @cite{Ada Reference Manual}. 122Those familiar with that document should be able to quickly 123lookup style rules for particular constructs. 124 125 126@c ------------------------------------------------------------------------- 127@node Lexical Elements, Declarations and Types, General, Top 128@section Lexical Elements 129@c ------------------------------------------------------------------------- 130@cindex Lexical elements 131 132@subsection Character Set and Separators 133@c ------------------------------------------------------------------------- 134@cindex Character set 135@cindex ASCII 136@cindex Separators 137@cindex End-of-line 138@cindex Line length 139@cindex Indentation 140 141@itemize @bullet 142@item 143The character set used should be plain 7-bit ASCII@. 144The only separators allowed are space and the end-of-line sequence. 145No other control character or format effector (such as @code{HT}, 146@code{VT}, @code{FF}) 147should be used. 148The normal end-of-line sequence is used, which may be 149@code{LF}, @code{CR/LF} or @code{CR}, 150depending on the host system. An optional @code{SUB} 151(@code{16#1A#}) may be present as the 152last character in the file on hosts using that character as file terminator. 153 154@item 155Files that are checked in or distributed should be in host format. 156 157@item 158A line should never be longer than 79 characters, not counting the line 159separator. 160 161@item 162Lines must not have trailing blanks. 163 164@item 165Indentation is 3 characters per level for @code{if} statements, loops, and 166@code{case} statements. 167For exact information on required spacing between lexical 168elements, see file @file{style.adb}. 169@cindex @file{style.adb} file 170@end itemize 171 172 173@subsection Identifiers 174@c ------------------------------------------------------------------------- 175@itemize @bullet 176@cindex Identifiers 177 178@item 179Identifiers will start with an upper case letter, and each letter following 180an underscore will be upper case. 181@cindex Casing (for identifiers) 182Short acronyms may be all upper case. 183All other letters are lower case. 184An exception is for identifiers matching a foreign language. In particular, 185we use all lower case where appropriate for C@. 186 187@item 188Use underscores to separate words in an identifier. 189@cindex Underscores 190 191@item Try to limit your use of abbreviations in identifiers. 192It is ok to make a few abbreviations, explain what they mean, and then 193use them frequently, but don't use lots of obscure abbreviations. An 194example is the @code{ALI} word which stands for Ada Library 195Information and is by convention always written in upper-case when 196used in entity names. 197 198@smallexample @c adanocomment 199 procedure Find_ALI_Files; 200@end smallexample 201 202@item 203Don't use the variable name @code{I}, use @code{J} instead; @code{I} is too 204easily confused with @code{1} in some fonts. Similarly don't use the 205variable @code{O}, which is too easily mistaken for the number @code{0}. 206@end itemize 207 208@subsection Numeric Literals 209@c ------------------------------------------------------------------------- 210@cindex Numeric literals 211 212@itemize @bullet 213@item 214Numeric literals should include underscores where helpful for 215readability. 216@cindex Underscores 217 218@smallexample 219 1_000_000 220 16#8000_000# 221 3.14159_26535_89793_23846 222@end smallexample 223@end itemize 224 225@subsection Reserved Words 226@c ------------------------------------------------------------------------- 227@cindex Reserved words 228 229@itemize @bullet 230@item 231Reserved words use all lower case. 232@cindex Casing (for reserved words) 233 234@smallexample @c adanocomment 235 return else 236@end smallexample 237 238@item 239The words @code{Access}, @code{Delta} and @code{Digits} are 240capitalized when used as @syntax{attribute_designator}. 241@end itemize 242 243@subsection Comments 244@c ------------------------------------------------------------------------- 245@cindex Comments 246 247@itemize @bullet 248@item 249A comment starts with @code{--} followed by two spaces). 250The only exception to this rule (i.e.@: one space is tolerated) is when the 251comment ends with a single space followed by @code{--}. 252It is also acceptable to have only one space between @code{--} and the start 253of the comment when the comment is at the end of a line, 254after some Ada code. 255 256@item 257Every sentence in a comment should start with an upper-case letter (including 258the first letter of the comment). 259@cindex Casing (in comments) 260 261@item 262When declarations are commented with ``hanging'' comments, i.e.@: 263comments after the declaration, there is no blank line before the 264comment, and if it is absolutely necessary to have blank lines within 265the comments these blank lines @emph{do} have a @code{--} (unlike the 266normal rule, which is to use entirely blank lines for separating 267comment paragraphs). The comment starts at same level of indentation 268as code it is commenting. 269@cindex Blank lines (in comments) 270@cindex Indentation 271 272@smallexample @c adanocomment 273 z : Integer; 274 -- Integer value for storing value of z 275 -- 276 -- The previous line was a blank line. 277@end smallexample 278 279@item 280Comments that are dubious or incomplete, or that comment on possibly 281wrong or incomplete code, should be preceded or followed by @code{???}@. 282 283@item 284Comments in a subprogram body must generally be surrounded by blank lines. 285An exception is a comment that follows a line containing a single keyword 286(@code{begin}, @code{else}, @code{loop}): 287 288@smallexample @c adanocomment 289@group 290 begin 291 -- Comment for the next statement 292 293 A := 5; 294 295 -- Comment for the B statement 296 297 B := 6; 298 end; 299@end group 300@end smallexample 301 302@item 303In sequences of statements, comments at the end of the lines should be 304aligned. 305@cindex Alignment (in comments) 306 307@smallexample @c adanocomment 308 My_Identifier := 5; -- First comment 309 Other_Id := 6; -- Second comment 310@end smallexample 311 312@item 313Short comments that fit on a single line are @emph{not} ended with a 314period. Comments taking more than a line are punctuated in the normal 315manner. 316 317@item 318Comments should focus on @emph{why} instead of @emph{what}. 319Descriptions of what subprograms do go with the specification. 320 321@item 322Comments describing a subprogram spec should specifically mention the 323formal argument names. General rule: write a comment that does not 324depend on the names of things. The names are supplementary, not 325sufficient, as comments. 326 327@item 328@emph{Do not} put two spaces after periods in comments. 329@end itemize 330 331@c ------------------------------------------------------------------------- 332@node Declarations and Types, Expressions and Names, Lexical Elements,Top 333@section Declarations and Types 334@c ------------------------------------------------------------------------- 335@cindex Declarationa and Types 336 337@itemize @bullet 338@item 339In entity declarations, colons must be surrounded by spaces. Colons 340should be aligned. 341@cindex Alignment (in declarations) 342 343@smallexample @c adanocomment 344 Entity1 : Integer; 345 My_Entity : Integer; 346@end smallexample 347 348@item 349Declarations should be grouped in a logical order. 350Related groups of declarations may be preceded by a header comment. 351 352@item 353All local subprograms in a subprogram or package body should be declared 354before the first local subprogram body. 355 356@item 357Do not declare local entities that hide global entities. 358@cindex Hiding of outer entities 359 360@item 361Do not declare multiple variables in one declaration that spans lines. 362Start a new declaration on each line, instead. 363 364@item 365The @syntax{defining_identifier}s of global declarations serve as 366comments of a sort. So don't choose terse names, but look for names 367that give useful information instead. 368 369@item 370Local names can be shorter, because they are used only within 371one context, where comments explain their purpose. 372 373@end itemize 374 375 376@c ------------------------------------------------------------------------- 377@node Expressions and Names, Statements, Declarations and Types, Top 378@section Expressions and Names 379@c ------------------------------------------------------------------------- 380@cindex Expressions and names 381 382@itemize @bullet 383 384@item 385Every operator must be surrounded by spaces. An exception is that 386this rule does not apply to the exponentiation operator, for which 387there are no specific layout rules. The reason for this exception 388is that sometimes it makes clearer reading to leave out the spaces 389around exponentiation. 390@cindex Operators 391 392@smallexample @c adanocomment 393 E := A * B**2 + 3 * (C - D); 394@end smallexample 395 396@item 397Use parentheses where they clarify the intended association of operands 398with operators: 399@cindex Parenthesization of expressions 400@smallexample @c adanocomment 401 (A / B) * C 402@end smallexample 403@end itemize 404 405@c ------------------------------------------------------------------------- 406@node Statements, Subprograms, Expressions and Names, Top 407@section Statements 408@c ------------------------------------------------------------------------- 409@cindex Statements 410 411@subsection Simple and Compound Statements 412@c ------------------------------------------------------------------------- 413@cindex Simple and compound statements 414 415@itemize @bullet 416@item 417Use only one statement or label per line. 418@item 419A longer @syntax{sequence_of_statements} may be divided in logical 420groups or separated from surrounding code using a blank line. 421@end itemize 422 423@subsection If Statements 424@c ------------------------------------------------------------------------- 425@cindex @code{if} statement 426 427@itemize @bullet 428@item 429When the @code{if}, @code{elsif} or @code{else} keywords fit on the 430same line with the condition and the @code{then} keyword, then the 431statement is formatted as follows: 432@cindex Alignment (in an @code{if} statement) 433 434@smallexample @c adanocomment 435@group 436 if @var{condition} then 437 ... 438 elsif @var{condition} then 439 ... 440 else 441 ... 442 end if; 443@end group 444@end smallexample 445 446@noindent 447When the above layout is not possible, @code{then} should be aligned 448with @code{if}, and conditions should preferably be split before an 449@code{and} or @code{or} keyword a follows: 450 451@smallexample @c adanocomment 452@group 453 if @var{long_condition_that_has_to_be_split} 454 and then @var{continued_on_the_next_line} 455 then 456 ... 457 end if; 458@end group 459@end smallexample 460 461@noindent 462The @code{elsif}, @code{else} and @code{end if} always line up with 463the @code{if} keyword. The preferred location for splitting the line 464is before @code{and} or @code{or}. The continuation of a condition is 465indented with two spaces or as many as needed to make nesting clear. 466As an exception, if conditions are closely related either of the 467following is allowed: 468 469@smallexample 470@group 471 if x = lakdsjfhlkashfdlkflkdsalkhfsalkdhflkjdsahf 472 or else 473 x = asldkjhalkdsjfhhfd 474 or else 475 x = asdfadsfadsf 476 then 477 ... 478 end if; 479@end group 480 481@group 482 if x = lakdsjfhlkashfdlkflkdsalkhfsalkdhflkjdsahf or else 483 x = asldkjhalkdsjfhhfd or else 484 x = asdfadsfadsf 485 then 486 ... 487 end if; 488@end group 489@end smallexample 490 491@item 492Conditions should use short-circuit forms (@code{and then}, 493@code{or else}). 494@cindex Short-circuit forms 495 496@item 497Complex conditions in @code{if} statements are indented two characters: 498@cindex Indentation (in @code{if} statements) 499 500@smallexample @c adanocomment 501@group 502 if @var{this_complex_condition} 503 and then @var{that_other_one} 504 and then @var{one_last_one} 505 then 506 ... 507 end if; 508@end group 509@end smallexample 510 511@item 512Every @code{if} block is preceded and followed by a blank line, except 513where it begins or ends a @syntax{sequence_of_statements}. 514@cindex Blank lines (in an @code{if} statement) 515 516@smallexample @c adanocomment 517@group 518 A := 5; 519 520 if A = 5 then 521 null; 522 end if; 523 524 A := 6; 525@end group 526@end smallexample 527@end itemize 528 529@subsection Case Statements 530@cindex @code{case} statements 531 532@itemize @bullet 533@item 534Layout is as below. For long @code{case} statements, the extra indentation 535can be saved by aligning the @code{when} clauses with the opening @code{case}. 536 537@smallexample @c adanocomment 538@group 539 case @var{expression} is 540 when @var{condition} => 541 ... 542 when @var{condition} => 543 ... 544 end case; 545@end group 546@end smallexample 547@end itemize 548 549@subsection Loop Statements 550@cindex Loop statements 551 552@itemize @bullet 553@noindent 554When possible, have @code{for} or @code{while} on one line with the 555condition and the @code{loop} keyword. 556 557@smallexample @c adanocomment 558@group 559 for J in S'Range loop 560 ... 561 end loop; 562@end group 563@end smallexample 564 565@noindent 566If the condition is too long, split the condition (see ``If 567statements'' above) and align @code{loop} with the @code{for} or 568@code{while} keyword. 569@cindex Alignment (in a loop statement) 570 571@smallexample @c adanocomment 572@group 573 while @var{long_condition_that_has_to_be_split} 574 and then @var{continued_on_the_next_line} 575 loop 576 ... 577 end loop; 578@end group 579@end smallexample 580 581@noindent 582If the @syntax{loop_statement} has an identifier, it is laid out as follows: 583 584@smallexample @c adanocomment 585@group 586 Outer : while not @var{condition} loop 587 ... 588 end Outer; 589@end group 590@end smallexample 591@end itemize 592 593@subsection Block Statements 594@cindex Block statement 595 596@itemize @bullet 597@item 598The @code{declare} (optional), @code{begin} and @code{end} words 599are aligned, except when the @syntax{block_statement} is named. There 600is a blank line before the @code{begin} keyword: 601@cindex Alignment (in a block statement) 602 603@smallexample @c adanocomment 604@group 605 Some_Block : declare 606 ... 607 608 begin 609 ... 610 end Some_Block; 611@end group 612@end smallexample 613 614@end itemize 615 616@c ------------------------------------------------------------------------- 617@node Subprograms, Packages, Statements, Top 618@section Subprograms 619@c ------------------------------------------------------------------------- 620@cindex Subprograms 621 622@subsection Subprogram Declarations 623@c ------------------------------------------------------------------------- 624@itemize @bullet 625 626@item 627Do not write the @code{in} for parameters, especially in functions: 628 629@smallexample @c adanocomment 630 function Length (S : String) return Integer; 631@end smallexample 632 633@item 634When the declaration line for a procedure or a function is too long to fit 635the entire declaration (including the keyword procedure or function) on a 636single line, then fold it, putting a single parameter on a line, aligning 637the colons, as in: 638 639@smallexample @c adanocomment 640@group 641 procedure Set_Heading 642 (Source : String; 643 Count : Natural; 644 Pad : Character := Space; 645 Fill : Boolean := True); 646@end group 647@end smallexample 648 649@noindent 650In the case of a function, if the entire spec does not fit on one line, then 651the return may appear after the last parameter, as in: 652 653@smallexample @c adanocomment 654@group 655 function Head 656 (Source : String; 657 Count : Natural; 658 Pad : Character := Space) return String; 659@end group 660@end smallexample 661 662@noindent 663Or it may appear on its own as a separate line. This form is preferred when 664putting the return on the same line as the last parameter would result in 665an overlong line. The return type may optionally be aligned with the types 666of the parameters (usually we do this aligning if it results only in a small 667number of extra spaces, and otherwise we don't attempt to align). So two 668alternative forms for the above spec are: 669 670@smallexample @c adanocomment 671@group 672 function Head 673 (Source : String; 674 Count : Natural; 675 Pad : Character := Space) 676 return String; 677 678 function Head 679 (Source : String; 680 Count : Natural; 681 Pad : Character := Space) 682 return String; 683@end group 684@end smallexample 685 686@end itemize 687 688@subsection Subprogram Bodies 689@c ------------------------------------------------------------------------- 690@cindex Subprogram bodies 691 692@itemize @bullet 693@item 694Function and procedure bodies should usually be sorted alphabetically. Do 695not attempt to sort them in some logical order by functionality. For a 696sequence of subrpgroams specs, a general alphabetical sorting is also 697usually appropriate, but occasionally it makes sense to group by major 698function, with appropriate headers. 699 700@item 701All subprograms have a header giving the function name, with the following 702format: 703 704@smallexample @c adanocomment 705@group 706 ----------------- 707 -- My_Function -- 708 ----------------- 709 710 procedure My_Function is 711 begin 712 ... 713 end My_Function; 714@end group 715@end smallexample 716 717@noindent 718Note that the name in the header is preceded by a single space, 719not two spaces as for other comments. 720 721@item 722Every subprogram body must have a preceding @syntax{subprogram_declaration}. 723 724@item 725@cindex Blank lines (in subprogram bodies) 726A sequence of declarations may optionally be separated from the following 727begin by a blank line. Just as we optionally allow blank lines in general 728between declarations, this blank line should be present only if it improves 729readability. Generally we avoid this blank line if the declarative part is 730small (one or two lines) and we include it if the declarative part is long. 731 732@item 733If the declarations in a subprogram contain at least one nested 734subprogram body, then just before the @code{begin} of the enclosing 735subprogram, there is a comment line and a blank line: 736 737@smallexample @c adanocomment 738@group 739 -- Start of processing for @var{Enclosing_Subprogram} 740 741 begin 742 ... 743 end @var{Enclosing_Subprogram}; 744@end group 745@end smallexample 746 747@end itemize 748 749@c ------------------------------------------------------------------------- 750@node Packages, Program Structure, Subprograms, Top 751@section Packages and Visibility Rules 752@c ------------------------------------------------------------------------- 753@cindex Packages 754 755@itemize @bullet 756@item 757All program units and subprograms have their name at the end: 758 759@smallexample @c adanocomment 760@group 761 package P is 762 ... 763 end P; 764@end group 765@end smallexample 766 767@item 768We will use the style of @code{use}-ing @code{with}-ed packages, with 769the context clauses looking like: 770@cindex @code{use} clauses 771 772@smallexample @c adanocomment 773@group 774 with A; use A; 775 with B; use B; 776@end group 777@end smallexample 778 779@item 780Names declared in the visible part of packages should be 781unique, to prevent name clashes when the packages are @code{use}d. 782@cindex Name clash avoidance 783 784@smallexample @c adanocomment 785@group 786 package Entity is 787 type Entity_Kind is ...; 788 ... 789 end Entity; 790@end group 791@end smallexample 792 793@item 794After the file header comment, the context clause and unit specification 795should be the first thing in a @syntax{program_unit}. 796@end itemize 797 798@c ------------------------------------------------------------------------- 799@node Program Structure, GNU Free Documentation License, Packages, Top 800@section Program Structure and Compilation Issues 801@c ------------------------------------------------------------------------- 802@cindex Program structure 803 804@itemize @bullet 805@item 806Every GNAT source file must be compiled with the @option{-gnatg} 807switch to check the coding style. 808(Note that you should look at 809@file{style.adb} to see the lexical rules enforced by 810@option{-gnatg}). 811@cindex @option{-gnatg} option (to gcc) 812@cindex @file{style.adb} file 813 814@item 815Each source file should contain only one compilation unit. 816 817@item 818Filenames should be 8 or fewer characters, followed by the @code{.adb} 819extension for a body or @code{.ads} for a spec. 820@cindex File name length 821 822@item 823Unit names should be distinct when ``krunch''ed to 8 characters 824(see @file{krunch.ads}) and the filenames should match the unit name, 825except that they are all lower case. 826@cindex @file{krunch.ads} file 827@end itemize 828 829 830@c ********************************** 831@c * GNU Free Documentation License * 832@c ********************************** 833@include fdl.texi 834@c GNU Free Documentation License 835@cindex GNU Free Documentation License 836 837@node Index,,GNU Free Documentation License, Top 838@unnumberedsec Index 839 840@printindex cp 841 842@contents 843 844@bye 845