|
111
|
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
|
|
|
17 Copyright @copyright{} 1992-2012, AdaCore
|
|
|
18
|
|
|
19 Permission is granted to copy, distribute and/or modify this document
|
|
|
20 under the terms of the GNU Free Documentation License, Version 1.3 or
|
|
|
21 any later version published by the Free Software Foundation; with no
|
|
|
22 Invariant Sections, with no Front-Cover Texts and with no Back-Cover
|
|
|
23 Texts. 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
|
|
|
62 GNAT Coding Style@*
|
|
|
63 A Guide for GNAT Developers
|
|
|
64 @sp 2
|
|
|
65 @noindent
|
|
|
66 GNAT, 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
|
|
|
92 Most of GNAT is written in Ada using a consistent style to ensure
|
|
|
93 readability of the code. This document has been written to help
|
|
|
94 maintain this consistent style, while having a large group of developers
|
|
|
95 work on the compiler.
|
|
|
96
|
|
|
97 For the coding style in the C parts of the compiler and run time,
|
|
|
98 see the GNU Coding Guidelines.
|
|
|
99
|
|
|
100 This document is structured after the @cite{Ada Reference Manual}.
|
|
|
101 Those familiar with that document should be able to quickly
|
|
|
102 lookup 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
|
|
|
122 The character set used should be plain 7-bit ASCII@.
|
|
|
123 The only separators allowed are space and the end-of-line sequence.
|
|
|
124 No other control character or format effector (such as @code{HT},
|
|
|
125 @code{VT}, @code{FF})
|
|
|
126 should be used.
|
|
|
127 The normal end-of-line sequence is used, which may be
|
|
|
128 @code{LF}, @code{CR/LF} or @code{CR},
|
|
|
129 depending on the host system. An optional @code{SUB}
|
|
|
130 (@code{16#1A#}) may be present as the
|
|
|
131 last character in the file on hosts using that character as file terminator.
|
|
|
132
|
|
|
133 @item
|
|
|
134 Files that are checked in or distributed should be in host format.
|
|
|
135
|
|
|
136 @item
|
|
|
137 A line should never be longer than 79 characters, not counting the line
|
|
|
138 separator.
|
|
|
139
|
|
|
140 @item
|
|
|
141 Lines must not have trailing blanks.
|
|
|
142
|
|
|
143 @item
|
|
|
144 Indentation is 3 characters per level for @code{if} statements, loops, and
|
|
|
145 @code{case} statements.
|
|
|
146 For exact information on required spacing between lexical
|
|
|
147 elements, 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
|
|
|
158 Identifiers will start with an upper case letter, and each letter following
|
|
|
159 an underscore will be upper case.
|
|
|
160 @cindex Casing (for identifiers)
|
|
|
161 Short acronyms may be all upper case.
|
|
|
162 All other letters are lower case.
|
|
|
163 An exception is for identifiers matching a foreign language. In particular,
|
|
|
164 we use all lower case where appropriate for C@.
|
|
|
165
|
|
|
166 @item
|
|
|
167 Use underscores to separate words in an identifier.
|
|
|
168 @cindex Underscores
|
|
|
169
|
|
|
170 @item Try to limit your use of abbreviations in identifiers.
|
|
|
171 It is ok to make a few abbreviations, explain what they mean, and then
|
|
|
172 use them frequently, but don't use lots of obscure abbreviations. An
|
|
|
173 example is the @code{ALI} word which stands for Ada Library
|
|
|
174 Information and is by convention always written in upper-case when
|
|
|
175 used in entity names.
|
|
|
176
|
|
|
177 @smallexample @c adanocomment
|
|
|
178 procedure Find_ALI_Files;
|
|
|
179 @end smallexample
|
|
|
180
|
|
|
181 @item
|
|
|
182 Don't use the variable name @code{I}, use @code{J} instead; @code{I} is too
|
|
|
183 easily confused with @code{1} in some fonts. Similarly don't use the
|
|
|
184 variable @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
|
|
|
193 Numeric literals should include underscores where helpful for
|
|
|
194 readability.
|
|
|
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
|
|
|
210 Reserved 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
|
|
|
218 The words @code{Access}, @code{Delta} and @code{Digits} are
|
|
|
219 capitalized when used as @syntax{attribute_designator}.
|
|
|
220 @end itemize
|
|
|
221
|
|
|
222 @subsection Comments
|
|
|
223 @c -------------------------------------------------------------------------
|
|
|
224 @cindex Comments
|
|
|
225
|
|
|
226 @itemize @bullet
|
|
|
227 @item
|
|
|
228 A comment starts with @code{--} followed by two spaces.
|
|
|
229 The only exception to this rule (i.e.@: one space is tolerated) is when the
|
|
|
230 comment ends with a single space followed by @code{--}.
|
|
|
231 It is also acceptable to have only one space between @code{--} and the start
|
|
|
232 of the comment when the comment is at the end of a line,
|
|
|
233 after some Ada code.
|
|
|
234
|
|
|
235 @item
|
|
|
236 Every sentence in a comment should start with an upper-case letter (including
|
|
|
237 the first letter of the comment).
|
|
|
238 @cindex Casing (in comments)
|
|
|
239
|
|
|
240 @item
|
|
|
241 When declarations are commented with ``hanging'' comments, i.e.@:
|
|
|
242 comments after the declaration, there is no blank line before the
|
|
|
243 comment, and if it is absolutely necessary to have blank lines within
|
|
|
244 the comments, e.g. to make paragraph separations within a single comment,
|
|
|
245 these blank lines @emph{do} have a @code{--} (unlike the
|
|
|
246 normal rule, which is to use entirely blank lines for separating
|
|
|
247 comment paragraphs). The comment starts at same level of indentation
|
|
|
248 as 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
|
|
|
260 Comments that are dubious or incomplete, or that comment on possibly
|
|
|
261 wrong or incomplete code, should be preceded or followed by @code{???}@.
|
|
|
262
|
|
|
263 @item
|
|
|
264 Comments in a subprogram body must generally be surrounded by blank lines.
|
|
|
265 An 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
|
|
|
283 In sequences of statements, comments at the end of the lines should be
|
|
|
284 aligned.
|
|
|
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
|
|
|
293 Short comments that fit on a single line are @emph{not} ended with a
|
|
|
294 period. Comments taking more than a line are punctuated in the normal
|
|
|
295 manner.
|
|
|
296
|
|
|
297 @item
|
|
|
298 Comments should focus on @emph{why} instead of @emph{what}.
|
|
|
299 Descriptions of what subprograms do go with the specification.
|
|
|
300
|
|
|
301 @item
|
|
|
302 Comments describing a subprogram spec should specifically mention the
|
|
|
303 formal argument names. General rule: write a comment that does not
|
|
|
304 depend on the names of things. The names are supplementary, not
|
|
|
305 sufficient, 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
|
|
|
319 In entity declarations, colons must be surrounded by spaces. Colons
|
|
|
320 should 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
|
|
|
329 Declarations should be grouped in a logical order.
|
|
|
330 Related groups of declarations may be preceded by a header comment.
|
|
|
331
|
|
|
332 @item
|
|
|
333 All local subprograms in a subprogram or package body should be declared
|
|
|
334 before the first local subprogram body.
|
|
|
335
|
|
|
336 @item
|
|
|
337 Do not declare local entities that hide global entities.
|
|
|
338 @cindex Hiding of outer entities
|
|
|
339
|
|
|
340 @item
|
|
|
341 Do not declare multiple variables in one declaration that spans lines.
|
|
|
342 Start a new declaration on each line, instead.
|
|
|
343
|
|
|
344 @item
|
|
|
345 The @syntax{defining_identifier}s of global declarations serve as
|
|
|
346 comments of a sort. So don't choose terse names, but look for names
|
|
|
347 that give useful information instead.
|
|
|
348
|
|
|
349 @item
|
|
|
350 Local names can be shorter, because they are used only within
|
|
|
351 one context, where comments explain their purpose.
|
|
|
352
|
|
|
353 @item
|
|
|
354 When starting an initialization or default expression on the line that follows
|
|
|
355 the 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
|
|
|
363 If an initialization or default expression needs to be continued on subsequent
|
|
|
364 lines, 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
|
|
|
383 Every operator must be surrounded by spaces. An exception is that
|
|
|
384 this rule does not apply to the exponentiation operator, for which
|
|
|
385 there are no specific layout rules. The reason for this exception
|
|
|
386 is that sometimes it makes clearer reading to leave out the spaces
|
|
|
387 around exponentiation.
|
|
|
388 @cindex Operators
|
|
|
389
|
|
|
390 @smallexample @c adanocomment
|
|
|
391 E := A * B**2 + 3 * (C - D);
|
|
|
392 @end smallexample
|
|
|
393
|
|
|
394 @item
|
|
|
395 Use parentheses where they clarify the intended association of operands
|
|
|
396 with 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
|
|
|
415 Use only one statement or label per line.
|
|
|
416 @item
|
|
|
417 A longer @syntax{sequence_of_statements} may be divided in logical
|
|
|
418 groups 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
|
|
|
427 When the @code{if}, @code{elsif} or @code{else} keywords fit on the
|
|
|
428 same line with the condition and the @code{then} keyword, then the
|
|
|
429 statement 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
|
|
|
445 When the above layout is not possible, @code{then} should be aligned
|
|
|
446 with @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
|
|
|
460 The @code{elsif}, @code{else} and @code{end if} always line up with
|
|
|
461 the @code{if} keyword. The preferred location for splitting the line
|
|
|
462 is before @code{and} or @code{or}. The continuation of a condition is
|
|
|
463 indented with two spaces or as many as needed to make nesting clear.
|
|
|
464 As an exception, if conditions are closely related either of the
|
|
|
465 following 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
|
|
|
490 Conditions should use short-circuit forms (@code{and then},
|
|
|
491 @code{or else}), except when the operands are boolean variables
|
|
|
492 or boolean constants.
|
|
|
493 @cindex Short-circuit forms
|
|
|
494
|
|
|
495 @item
|
|
|
496 Complex 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
|
|
|
511 There are some cases where complex conditionals can be laid out
|
|
|
512 in manners that do not follow these rules to preserve better
|
|
|
513 parallelism 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
|
|
|
528 Every @code{if} block is preceded and followed by a blank line, except
|
|
|
529 where 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
|
|
|
550 Layout is as below. For long @code{case} statements, the extra indentation
|
|
|
551 can 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 @item
|
|
|
570 When possible, have @code{for} or @code{while} on one line with the
|
|
|
571 condition 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
|
|
|
582 If the condition is too long, split the condition (see ``If
|
|
|
583 statements'' 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
|
|
|
598 If 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
|
|
|
614 The @code{declare} (optional), @code{begin} and @code{end} words
|
|
|
615 are aligned, except when the @syntax{block_statement} is named. There
|
|
|
616 is 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
|
|
|
643 Do 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
|
|
|
650 When the declaration line for a procedure or a function is too long to fit
|
|
|
651 the entire declaration (including the keyword procedure or function) on a
|
|
|
652 single line, then fold it, putting a single parameter on a line, aligning
|
|
|
653 the 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
|
|
|
666 In the case of a function, if the entire spec does not fit on one line, then
|
|
|
667 the 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
|
|
|
679 Or it may appear on its own as a separate line. This form is preferred when
|
|
|
680 putting the return on the same line as the last parameter would result in
|
|
|
681 an overlong line. The return type may optionally be aligned with the types
|
|
|
682 of the parameters (usually we do this aligning if it results only in a small
|
|
|
683 number of extra spaces, and otherwise we don't attempt to align). So two
|
|
|
684 alternative 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
|
|
|
710 Function and procedure bodies should usually be sorted alphabetically. Do
|
|
|
711 not attempt to sort them in some logical order by functionality. For a
|
|
|
712 sequence of subprogram specs, a general alphabetical sorting is also
|
|
|
713 usually appropriate, but occasionally it makes sense to group by major
|
|
|
714 function, with appropriate headers.
|
|
|
715
|
|
|
716 @item
|
|
|
717 All subprograms have a header giving the function name, with the following
|
|
|
718 format:
|
|
|
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
|
|
|
734 Note that the name in the header is preceded by a single space,
|
|
|
735 not two spaces as for other comments. These headers are used on
|
|
|
736 nested subprograms as well as outer level subprograms. They may
|
|
|
737 also be used as headers for sections of comments, or collections
|
|
|
738 of declarations that are related.
|
|
|
739
|
|
|
740 @item
|
|
|
741 Every subprogram body must have a preceding @syntax{subprogram_declaration},
|
|
|
742 which includes proper client documentation so that you do not need to
|
|
|
743 read the subprogram body in order to understand what the subprogram does and
|
|
|
744 how to call it. All subprograms should be documented, without exceptions.
|
|
|
745
|
|
|
746 @item
|
|
|
747 @cindex Blank lines (in subprogram bodies)
|
|
|
748 A sequence of declarations may optionally be separated from the following
|
|
|
749 begin by a blank line. Just as we optionally allow blank lines in general
|
|
|
750 between declarations, this blank line should be present only if it improves
|
|
|
751 readability. Generally we avoid this blank line if the declarative part is
|
|
|
752 small (one or two lines) and the body has no blank lines, and we include it
|
|
|
753 if the declarative part is long or if the body has blank lines.
|
|
|
754
|
|
|
755 @item
|
|
|
756 If the declarations in a subprogram contain at least one nested
|
|
|
757 subprogram body, then just before the @code{begin} of the enclosing
|
|
|
758 subprogram, 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
|
|
|
771 When nested subprograms are present, variables that are referenced by any
|
|
|
772 nested subprogram should precede the nested subprogram specs. For variables
|
|
|
773 that are not referenced by nested procedures, the declarations can either also
|
|
|
774 be before any of the nested subprogram specs (this is the old style, more
|
|
|
775 generally used). Or then can come just before the begin, with a header. The
|
|
|
776 following 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
|
|
|
835 For new code, we generally prefer Style2, but we do not insist on
|
|
|
836 modifying all legacy occurrences of Style1, which is still much
|
|
|
837 more 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
|
|
|
850 All 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
|
|
|
861 We will use the style of @code{use}-ing @code{with}-ed packages, with
|
|
|
862 the 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
|
|
|
873 Names declared in the visible part of packages should be
|
|
|
874 unique, 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
|
|
|
887 After the file header comment, the context clause and unit specification
|
|
|
888 should be the first thing in a @syntax{program_unit}.
|
|
|
889
|
|
|
890 @item
|
|
|
891 Preelaborate, Pure and Elaborate_Body pragmas should be added right after the
|
|
|
892 package 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
|
|
|
913 Every GNAT source file must be compiled with the @option{-gnatg}
|
|
|
914 switch 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
|
|
|
922 Each source file should contain only one compilation unit.
|
|
|
923
|
|
|
924 @item
|
|
|
925 Filenames should be 8 or fewer characters, followed by the @code{.adb}
|
|
|
926 extension for a body or @code{.ads} for a spec.
|
|
|
927 @cindex File name length
|
|
|
928
|
|
|
929 @item
|
|
|
930 Unit names should be distinct when ``krunch''ed to 8 characters
|
|
|
931 (see @file{krunch.ads}) and the filenames should match the unit name,
|
|
|
932 except 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 @node GNU Free Documentation License,Index, Program Structure, Top
|
|
|
941 @unnumberedsec GNU Free Documentation License
|
|
|
942 @set nodefaultgnufreedocumentationlicensenode
|
|
|
943 @include fdl.texi
|
|
|
944 @c GNU Free Documentation License
|
|
|
945 @cindex GNU Free Documentation License
|
|
|
946
|
|
|
947 @node Index,,GNU Free Documentation License, Top
|
|
|
948 @unnumberedsec Index
|
|
|
949
|
|
|
950 @printindex cp
|
|
|
951
|
|
|
952 @contents
|
|
|
953
|
|
|
954 @bye
|
