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