| blob | def4d03e5d757757d8f4ac7cd03028f59c835210 |
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 $Revision: 1.1 $
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
26 @setfilename gnat-style.info
27 @settitle GNAT Coding Style
28 @c %**end of header
30 @ifinfo
31 @center GNAT Coding Style
33 @center A guide for GNAT developers
34 Copyright (C) 1992-2001 Ada Core Technologies, Inc.
35 @end ifinfo
37 @titlepage
38 @sp 10
39 @title GNAT Coding Stye
40 @subtitle A guide for GNAT developers
41 @subtitle Document revision level $Revision: 1.1 $
42 @subtitle Date: @today{}
43 @author Ada Core Technologies, Inc.
44 @end titlepage
45 @raisesections
47 @node Top, General, , (dir)
48 @comment node-name, next, previous, up
50 @menu
51 * General::
52 * Lexical Elements::
53 * Declarations and Types::
54 * Expressions and Names::
55 * Statements::
56 * Subprograms::
57 * Packages::
58 * Program Structure::
59 @end menu
61 @c -------------------------------------------------------------------------
62 @node General, Lexical Elements, Top, Top
63 @section General
64 @c -------------------------------------------------------------------------
66 @noindent
67 Most of GNAT is written in Ada using a consistent style to ensure
68 readability of the code. This document has been written to help
69 maintain this consistent style, while having a large group of developers
70 work on the compiler.
72 @noindent
73 For the coding style in the C parts of the compiler and run time,
74 see the GNU Coding Guidelines.
76 @noindent
77 This document is structured after the Ada Reference manual.
78 Those familiar with that document should be able to quickly
79 lookup style rules for particular constructs.
81 @c -------------------------------------------------------------------------
82 @node Lexical Elements, Declarations and Types, General, Top
83 @section Lexical Elements
84 @c -------------------------------------------------------------------------
86 @subsection Character Set and Separators
87 @c -------------------------------------------------------------------------
89 @itemize @bullet
90 @item
91 The character set used should be plain 7-bit ASCII.
92 The only separators allowed are space and the end-of-line sequence.
93 No other control character or format effector (such as HT, VT, FF)
94 should be used.
95 The normal end-of-line sequence is used, which may be LF, CR/LF or CR,
96 depending on the host system. An optional SUB (16#1A#) may be present as the
97 last character in the file on hosts using that character as file terminator.
99 @item
100 Files that are checked in or distributed should be in host format.
102 @item
103 A line should never be longer than 79 characters, not counting the line
104 separator.
106 @item
107 Lines must not have trailing blanks.
109 @item
110 Indentation is 3 characters per level for if-statements, loops, case
111 statements. For exact information on required spacing between lexical
112 elements, see file @file{style.adb}.
114 @end itemize
116 @subsection Identifiers
117 @c -------------------------------------------------------------------------
118 @itemize @bullet
119 @item
120 Identifiers will start with an upper case letter, and each letter following
121 an underscore will be upper case. Short acronyms may be all upper case.
122 All other letters are lower case.
123 An exception is for identifiers matching a foreign language. In particular,
124 we use all lower case where appropriate for C.
126 @item
127 Use underscores to separate words in an identifier.
129 @item Try to limit your use of abbreviations in identifiers.
130 It is ok to make a few abbreviations, explain what they mean, and then use them frequently, but don't use lots of obscure abbreviations.
131 An example is the @code{ALI} word which stands for Ada Library Information
132 and is by convention always written in upper-case when used in entity names.
134 @smallexample
135 procedure Find_ALI_Files;
136 @end smallexample
138 @item
139 Don't use the variable I, use J instead, I is too easily mixed up with
140 1 in some fonts. Similarly don't use the variable O, which is too easily
141 mixed up with zero.
142 @end itemize
144 @subsection Numeric Literals
145 @c -------------------------------------------------------------------------
146 @itemize @bullet
147 @item
148 Numeric literals should include underscores where helpful for
149 readability.
151 @smallexample
152 1_000_000
153 16#8000_000#
154 3.14159_26535_89793_23846
155 @end smallexample
156 @end itemize
158 @subsection Reserved Words
159 @c -------------------------------------------------------------------------
160 @itemize @bullet
161 @item
162 Reserved words use all lower case.
164 @smallexample
165 return else
166 @end smallexample
168 @item
169 The words "Access", "Delta" and "Digits" are capitalized when used
170 as attribute_designator.
171 @end itemize
173 @subsection Comments
174 @c -------------------------------------------------------------------------
176 @itemize @bullet
177 @item
178 Comment start with @code{-- } (ie @code{--} followed by two spaces).
179 The only exception to this rule (i.e. one space is tolerated) is when the
180 comment ends with @code{--}.
181 It also accepted to have only one space between @code{--} and the start
182 of the comment when the comment is at the end of a line,
183 after an Ada statement.
185 @item
186 Every sentence in a comment should start with an upper-case letter (including
187 the first letter of the comment).
189 @item
190 When declarations are commented with "hanging" comments, i.e. comments
191 after the declaration, there is no blank line before the comment, and
192 if it is absolutely necessary to have blank lines within the comments
193 these blank lines *do* have a -- (unlike the normal rule, which is to
194 use entirely blank lines for separating comment paragraphs).
195 The comment start at same level of indentation as code they are commenting.
197 @smallexample
198 z : integer;
199 -- Integer value for storing value of z
200 --
201 -- The previous line was a blank line
202 @end smallexample
204 @item
205 Comments that are dubious or incomplete or comment on possibly
206 wrong or incomplete code should be preceded or followed by ???
208 @item
209 Comments in a subprogram body must generally be surrounded by blank lines,
210 except after a "begin":
212 @smallexample
213 begin
214 -- Comment for the next statement
216 A := 5;
218 -- Comment for the B statement
220 B := 6;
221 @end smallexample
223 @item
224 In sequences of statements, comments at the end of the lines should be
225 aligned.
227 @smallexample
228 My_Identifier := 5; -- First comment
229 Other_Id := 6; -- Second comment
230 @end smallexample
232 @item
233 Short comments that fit on a single line are NOT ended with a period.
234 Comments taking more than a line are punctuated in the normal manner.
236 @item
237 Comments should focus on why instead of what.
238 Descriptions of what subprograms do go with the specification.
240 @item
241 Comments describing a subprogram spec should specifically mention the
242 formal argument names. General rule: write a comment that does not
243 depend on the names of things. The names are supplementary, not
244 sufficient, as comments.
246 @item
247 Do NOT put two spaces after periods in comments.
248 @end itemize
250 @c -------------------------------------------------------------------------
251 @node Declarations and Types, Expressions and Names, Lexical Elements,Top
252 @section Declarations and Types
253 @c -------------------------------------------------------------------------
255 @itemize @bullet
256 @item
257 In entity declarations, colons must be surrounded by spaces. Colons
258 should be aligned.
260 @smallexample
261 Entity1 : Integer;
262 My_Entity : Integer;
263 @end smallexample
265 @item
266 Declarations should be grouped in a logical order.
267 Related groups of declarations may be preceded by a header comment.
269 @item
270 All local subprograms in a subprogram or package body should be declared
271 before the first local subprogram body.
273 @item
274 Do not declare discriminated record types where the discriminant is used
275 for constraining an unconstrained array type. (Discriminated
276 records for a variant part are allowed.)
278 @item
279 Don't declare local entities that hide global entities.
281 @item
282 Don't declare multiple variables in one declaration that spans lines.
283 Start a new declaration on each line, instead
285 @item
286 The defining_identifiers of global declarations serve as comments of a sort.
287 So don't choose terse names, but look for names that give useful information
288 instead.
290 @item
291 Local names can be shorter, because they are used only within
292 one context, where comments explain their purpose.
294 @end itemize
297 @c -------------------------------------------------------------------------
298 @node Expressions and Names, Statements, Declarations and Types, Top
299 @section Expressions and Names
300 @c -------------------------------------------------------------------------
302 @itemize @bullet
304 @item
305 Every operator must be surrounded by spaces, except for the
306 exponentiation operator.
308 @smallexample
309 E := A * B**2 + 3 * (C - D);
310 @end smallexample
312 @item
313 When folding a long line, fold before an operator, not after.
315 @item
316 Use parentheses where they make the intended order of evaluation clearer:
317 @smallexample
318 (A / B) * C
319 @end smallexample
320 @end itemize
322 @c -------------------------------------------------------------------------
323 @node Statements, Subprograms, Expressions and Names, Top
324 @section Statements
325 @c -------------------------------------------------------------------------
327 @subsection Simple and Compound Statements
328 @c -------------------------------------------------------------------------
329 @itemize @bullet
330 @item
331 Use only one statement or label per line.
332 @item
333 A longer sequence_of_statements may be divided in logical groups
334 or separated from surrounding code using a blank line.
335 @end itemize
337 @subsection If Statements
338 @c -------------------------------------------------------------------------
339 @itemize @bullet
340 @item
341 When the "if", "elsif" or "else" keywords fit on the same line with the
342 condition and the "then" keyword, then the statement is formatted as follows:
344 @smallexample
345 if <condition> then
346 ...
347 elsif <condition> then
348 ...
349 else
350 ...
351 end if;
352 @end smallexample
354 @noindent
355 When the above layout is not possible, "then" should be aligned with "if",
356 and conditions should preferably be split before an "and" or "or" keyword
357 a follows:
359 @smallexample
360 if <long_condition_that_has_to_be_split>
361 and then <continued_on_the_next_line>
362 then
363 ...
364 end if;
365 @end smallexample
367 @noindent
368 The "elsif", "else" and "end if" always line up with the "if" keyword. The
369 preferred location for splitting the line is before "and" or "or". The
370 continuation of a condition is indented with two spaces or as many as needed
371 to make nesting clear.
372 As exception, if conditions are closely related either of the following is
373 allowed:
375 @smallexample
376 if x = lakdsjfhlkashfdlkflkdsalkhfsalkdhflkjdsahf
377 or else
378 x = asldkjhalkdsjfhhfd
379 or else
380 x = asdfadsfadsf
381 then
383 if x = lakdsjfhlkashfdlkflkdsalkhfsalkdhflkjdsahf or else
384 x = asldkjhalkdsjfhhfd or else
385 x = asdfadsfadsf
386 then
387 @end smallexample
389 @item
390 Conditions should use short-circuit forms ("and then", "or else").
392 @item
393 Complex conditions in if-statements are indented two characters:
395 @smallexample
396 if this_complex_condition
397 and then that_other_one
398 and then one_last_one
399 then
400 ...
401 @end smallexample
403 @item
404 Every "if" block is preceded and followed by a blank line, except
405 where it begins or ends a sequence_of_statements.
407 @smallexample
408 A := 5;
410 if A = 5 then
411 null;
412 end if;
414 A := 6;
415 @end smallexample
416 @end itemize
418 @subsection Case statements
419 @itemize @bullet
421 @item
422 Layout is as below. For long case statements, the extra indentation
423 can be saved by aligning the when clauses with the opening case.
425 @smallexample
426 case <expression> is
427 when <condition> =>
428 ...
429 when <condition> =>
430 ...
431 end case;
432 @end smallexample
433 @end itemize
435 @subsection Loop statements
436 @itemize @bullet
438 @noindent
439 When possible, have "for" or "while" on one line with the condition
440 and the "loop" keyword.
442 @smallexample
443 for I in S'Range loop
444 ...
445 end loop;
446 @end smallexample
448 @noindent
449 If the condition is too long, split the condition (see if_statement)
450 and align "loop" with the "for" or "while" keyword.
452 @smallexample
453 while <long_condition_that_has_to_be_split>
454 and then <continued_on_the_next_line>
455 loop
456 ...
457 end loop;
458 @end smallexample
460 @noindent
461 If the loop_statement has an identifier, it is layout as follows:
463 @smallexample
464 Outer : while not <condition> loop
465 ...
466 end Outer;
467 @end smallexample
468 @end itemize
470 @subsection Block Statements
471 @itemize @bullet
473 @item
474 The (optional) "declare", "begin" and "end" statements are aligned,
475 except when the block_statement is named:
477 @smallexample
478 Some_Block : declare
479 ...
480 begin
481 ...
482 end Some_Block;
483 @end smallexample
485 @end itemize
487 @c -------------------------------------------------------------------------
488 @node Subprograms, Packages, Statements, Top
489 @section Subprograms
490 @c -------------------------------------------------------------------------
493 @subsection Subprogram Declarations
494 @c -------------------------------------------------------------------------
495 @itemize @bullet
497 @item
498 Do not write the "in" for parameters, especially in functions:
500 @smallexample
501 function Length (S : String) return Integer;
502 @end smallexample
504 @item
505 When the declaration line for a procedure or a function is too long, fold it.
507 @smallexample
508 function Head
509 (Source : String;
510 Count : Natural;
511 Pad : Character := Space)
512 return String;
513 @end smallexample
515 @item
516 The parameter list for a subprogram is preceded by a space:
518 @smallexample
519 procedure Func (A : Integer);
520 @end smallexample
522 @end itemize
524 @subsection Subprogram Bodies
525 @c -------------------------------------------------------------------------
526 @itemize @bullet
528 @item
529 The functions and procedures should always be sorted alphabetically in
530 a compilation unit.
532 @item
533 All subprograms have a header giving the function name, with the following
534 format:
536 @smallexample
537 -----------------
538 -- My_Function --
539 -----------------
541 procedure My_Function is
542 begin
543 @end smallexample
544 Note that the name in the header is preceded by a single space,
545 not two spaces as for other comments.
547 @item
548 Every subprogram body must have a preceding subprogram_declaration.
550 @item
551 If declarations of a subprogram contain at least one nested subprogram
552 body, then just before the begin is a line:
554 @smallexample
555 -- Start of processing for bla bla
557 begin
558 @end smallexample
560 @end itemize
562 @c -------------------------------------------------------------------------
563 @node Packages, Program Structure, Subprograms, Top
564 @section Packages and Visibility Rules
565 @c -------------------------------------------------------------------------
567 @itemize @bullet
569 @item
570 All program units and subprograms have their name at the end:
572 @smallexample
573 package P is
574 ...
575 end P;
576 @end smallexample
578 @item
579 We will use the style of use-ing with-ed packages, with the context
580 clauses looking like:
582 @smallexample
583 with A; use A;
584 with B; use B;
585 @end smallexample
587 @item
588 Names declared in the visible part of packages should be
589 unique, to prevent name clashes when the packages are "use"d.
591 @smallexample
592 package Entity is
593 type Entity_Kind is ...;
594 ...
595 end Entity;
596 @end smallexample
598 @item
599 After the file header comment, the context clause and unit specification
600 should be the first thing in a program_unit.
601 @end itemize
603 @c -------------------------------------------------------------------------
604 @node Program Structure,, Packages, Top
605 @section Program Structure and Compilation Issues
606 @c -------------------------------------------------------------------------
608 @itemize @bullet
609 @item
610 Every GNAT source file must be compiled with the "-gnatg" switch to check
611 the coding style (Note that you should look at @file{style.adb} to
612 see the lexical rules enforced by -gnatg).
614 @item
615 Each source file should contain only one compilation unit.
617 @item
618 Filenames should be 8 characters or less followed by the ".adb" extension
619 for a body or ".ads" for a spec.
621 @item
622 Unit names should be distinct when krunched to 8 characters
623 (see @file{krunch.ads}) and the filenames should match the unit name,
624 except that they are all lower case.
625 @end itemize
627 @bye