| 1 |
GNAT Coding Style: A Guide for GNAT Developers |
| 2 |
============================================== |
| 3 |
|
| 4 |
General |
| 5 |
------- |
| 6 |
|
| 7 |
Most of GNAT is written in Ada using a consistent style to ensure |
| 8 |
readability of the code. This document has been written to help |
| 9 |
maintain this consistent style, while having a large group of developers |
| 10 |
work on the compiler. |
| 11 |
|
| 12 |
For the coding style in the C parts of the compiler and run time, |
| 13 |
see the GNU Coding Guidelines. |
| 14 |
|
| 15 |
This document is structured after the Ada Reference Manual. |
| 16 |
Those familiar with that document should be able to quickly |
| 17 |
lookup style rules for particular constructs. |
| 18 |
|
| 19 |
Lexical Elements |
| 20 |
---------------- |
| 21 |
|
| 22 |
Character Set and Separators |
| 23 |
**************************** |
| 24 |
|
| 25 |
.. index:: Character set |
| 26 |
.. index:: ASCII |
| 27 |
.. index:: Separators |
| 28 |
.. index:: End-of-line |
| 29 |
.. index:: Line length |
| 30 |
.. index:: Indentation |
| 31 |
|
| 32 |
* The character set used should be plain 7-bit ASCII. |
| 33 |
The only separators allowed are space and the end-of-line sequence. |
| 34 |
No other control character or format effector (such as ``HT``, |
| 35 |
``VT``, ``FF`` ) |
| 36 |
should be used. |
| 37 |
The normal end-of-line sequence is used, which may be |
| 38 |
``LF``, ``CR/LF`` or ``CR``, |
| 39 |
depending on the host system. An optional ``SUB`` |
| 40 |
( ``16#1A#`` ) may be present as the |
| 41 |
last character in the file on hosts using that character as file terminator. |
| 42 |
|
| 43 |
* Files that are checked in or distributed should be in host format. |
| 44 |
|
| 45 |
* A line should never be longer than 79 characters, not counting the line |
| 46 |
separator. |
| 47 |
|
| 48 |
* Lines must not have trailing blanks. |
| 49 |
|
| 50 |
* Indentation is 3 characters per level for ``if`` statements, loops, and |
| 51 |
``case`` statements. |
| 52 |
For exact information on required spacing between lexical |
| 53 |
elements, see file style.adb. |
| 54 |
|
| 55 |
.. index:: style.adb file |
| 56 |
|
| 57 |
Identifiers |
| 58 |
*********** |
| 59 |
|
| 60 |
* Identifiers will start with an upper case letter, and each letter following |
| 61 |
an underscore will be upper case. |
| 62 |
|
| 63 |
.. index:: Casing (for identifiers) |
| 64 |
|
| 65 |
Short acronyms may be all upper case. |
| 66 |
All other letters are lower case. |
| 67 |
An exception is for identifiers matching a foreign language. In particular, |
| 68 |
we use all lower case where appropriate for C. |
| 69 |
|
| 70 |
* Use underscores to separate words in an identifier. |
| 71 |
|
| 72 |
.. index:: Underscores |
| 73 |
|
| 74 |
* Try to limit your use of abbreviations in identifiers. |
| 75 |
It is ok to make a few abbreviations, explain what they mean, and then |
| 76 |
use them frequently, but don't use lots of obscure abbreviations. An |
| 77 |
example is the ``ALI`` word which stands for Ada Library |
| 78 |
Information and is by convention always written in upper-case when |
| 79 |
used in entity names. |
| 80 |
|
| 81 |
.. code-block:: ada |
| 82 |
|
| 83 |
procedure Find_ALI_Files; |
| 84 |
|
| 85 |
* Don't use the variable name ``I``, use ``J`` instead; ``I`` is too |
| 86 |
easily confused with ``1`` in some fonts. Similarly don't use the |
| 87 |
variable ``O``, which is too easily mistaken for the number ``0``. |
| 88 |
|
| 89 |
Numeric Literals |
| 90 |
**************** |
| 91 |
|
| 92 |
* Numeric literals should include underscores where helpful for |
| 93 |
readability. |
| 94 |
|
| 95 |
.. index:: Underscores |
| 96 |
|
| 97 |
.. code-block:: ada |
| 98 |
|
| 99 |
1_000_000 |
| 100 |
16#8000_0000# |
| 101 |
3.14159_26535_89793_23846 |
| 102 |
|
| 103 |
Reserved Words |
| 104 |
************** |
| 105 |
|
| 106 |
* Reserved words use all lower case. |
| 107 |
|
| 108 |
.. index:: Casing (for reserved words) |
| 109 |
|
| 110 |
.. code-block:: ada |
| 111 |
|
| 112 |
return else |
| 113 |
|
| 114 |
* The words ``Access``, ``Delta`` and ``Digits`` are |
| 115 |
capitalized when used as attribute_designator. |
| 116 |
|
| 117 |
Comments |
| 118 |
******** |
| 119 |
|
| 120 |
* A comment starts with ``--`` followed by two spaces. |
| 121 |
The only exception to this rule (i.e. one space is tolerated) is when the |
| 122 |
comment ends with a single space followed by ``--``. |
| 123 |
It is also acceptable to have only one space between ``--`` and the start |
| 124 |
of the comment when the comment is at the end of a line, |
| 125 |
after some Ada code. |
| 126 |
|
| 127 |
* Every sentence in a comment should start with an upper-case letter (including |
| 128 |
the first letter of the comment). |
| 129 |
|
| 130 |
.. index:: Casing (in comments) |
| 131 |
|
| 132 |
* When declarations are commented with 'hanging' comments, i.e. |
| 133 |
comments after the declaration, there is no blank line before the |
| 134 |
comment, and if it is absolutely necessary to have blank lines within |
| 135 |
the comments, e.g. to make paragraph separations within a single comment, |
| 136 |
these blank lines *do* have a ``--`` (unlike the |
| 137 |
normal rule, which is to use entirely blank lines for separating |
| 138 |
comment paragraphs). The comment starts at same level of indentation |
| 139 |
as code it is commenting. |
| 140 |
|
| 141 |
.. index:: Blank lines (in comments) |
| 142 |
.. index:: Indentation |
| 143 |
|
| 144 |
.. code-block:: ada |
| 145 |
|
| 146 |
z : Integer; |
| 147 |
-- Integer value for storing value of z |
| 148 |
-- |
| 149 |
-- The previous line was a blank line. |
| 150 |
|
| 151 |
* Comments that are dubious or incomplete, or that comment on possibly |
| 152 |
wrong or incomplete code, should be preceded or followed by ``???``. |
| 153 |
|
| 154 |
* Comments in a subprogram body must generally be surrounded by blank lines. |
| 155 |
An exception is a comment that follows a line containing a single keyword |
| 156 |
( ``begin``, ``else``, ``loop`` ): |
| 157 |
|
| 158 |
.. code-block:: ada |
| 159 |
|
| 160 |
begin |
| 161 |
-- Comment for the next statement |
| 162 |
|
| 163 |
A := 5; |
| 164 |
|
| 165 |
-- Comment for the B statement |
| 166 |
|
| 167 |
B := 6; |
| 168 |
end; |
| 169 |
|
| 170 |
* In sequences of statements, comments at the end of the lines should be |
| 171 |
aligned. |
| 172 |
|
| 173 |
.. index:: Alignment (in comments) |
| 174 |
|
| 175 |
.. code-block:: ada |
| 176 |
|
| 177 |
My_Identifier := 5; -- First comment |
| 178 |
Other_Id := 6; -- Second comment |
| 179 |
|
| 180 |
* Short comments that fit on a single line are *not* ended with a |
| 181 |
period. Comments taking more than a line are punctuated in the normal |
| 182 |
manner. |
| 183 |
|
| 184 |
* Comments should focus on *why* instead of *what*. |
| 185 |
Descriptions of what subprograms do go with the specification. |
| 186 |
|
| 187 |
* Comments describing a subprogram spec should specifically mention the |
| 188 |
formal argument names. General rule: write a comment that does not |
| 189 |
depend on the names of things. The names are supplementary, not |
| 190 |
sufficient, as comments. |
| 191 |
|
| 192 |
* *Do not* put two spaces after periods in comments. |
| 193 |
|
| 194 |
Declarations and Types |
| 195 |
---------------------- |
| 196 |
|
| 197 |
* In entity declarations, colons must be surrounded by spaces. Colons |
| 198 |
should be aligned. |
| 199 |
|
| 200 |
.. index:: Alignment (in declarations) |
| 201 |
|
| 202 |
.. code-block:: ada |
| 203 |
|
| 204 |
Entity1 : Integer; |
| 205 |
My_Entity : Integer; |
| 206 |
|
| 207 |
* Declarations should be grouped in a logical order. |
| 208 |
Related groups of declarations may be preceded by a header comment. |
| 209 |
|
| 210 |
* All local subprograms in a subprogram or package body should be declared |
| 211 |
before the first local subprogram body. |
| 212 |
|
| 213 |
* Do not declare local entities that hide global entities. |
| 214 |
|
| 215 |
.. index:: Hiding of outer entities |
| 216 |
|
| 217 |
* Do not declare multiple variables in one declaration that spans lines. |
| 218 |
Start a new declaration on each line, instead. |
| 219 |
|
| 220 |
* The defining_identifiers of global declarations serve as |
| 221 |
comments of a sort. So don't choose terse names, but look for names |
| 222 |
that give useful information instead. |
| 223 |
|
| 224 |
* Local names can be shorter, because they are used only within |
| 225 |
one context, where comments explain their purpose. |
| 226 |
|
| 227 |
* When starting an initialization or default expression on the line that follows |
| 228 |
the declaration line, use 2 characters for indentation. |
| 229 |
|
| 230 |
.. code-block:: ada |
| 231 |
|
| 232 |
Entity1 : Integer := |
| 233 |
Function_Name (Parameters, For_Call); |
| 234 |
|
| 235 |
* If an initialization or default expression needs to be continued on subsequent |
| 236 |
lines, the continuations should be indented from the start of the expression. |
| 237 |
|
| 238 |
.. code-block:: ada |
| 239 |
|
| 240 |
Entity1 : Integer := Long_Function_Name |
| 241 |
(parameters for call); |
| 242 |
|
| 243 |
Expressions and Names |
| 244 |
--------------------- |
| 245 |
|
| 246 |
* Every operator must be surrounded by spaces. An exception is that |
| 247 |
this rule does not apply to the exponentiation operator, for which |
| 248 |
there are no specific layout rules. The reason for this exception |
| 249 |
is that sometimes it makes clearer reading to leave out the spaces |
| 250 |
around exponentiation. |
| 251 |
|
| 252 |
.. index:: Operators |
| 253 |
|
| 254 |
.. code-block:: ada |
| 255 |
|
| 256 |
E := A * B**2 + 3 * (C - D); |
| 257 |
|
| 258 |
* Use parentheses where they clarify the intended association of operands |
| 259 |
with operators: |
| 260 |
|
| 261 |
.. index:: Parenthesization of expressions |
| 262 |
|
| 263 |
.. code-block:: ada |
| 264 |
|
| 265 |
(A / B) * C |
| 266 |
|
| 267 |
Statements |
| 268 |
---------- |
| 269 |
|
| 270 |
Simple and Compound Statements |
| 271 |
****************************** |
| 272 |
|
| 273 |
* Use only one statement or label per line. |
| 274 |
|
| 275 |
* A longer sequence_of_statements may be divided in logical |
| 276 |
groups or separated from surrounding code using a blank line. |
| 277 |
|
| 278 |
|
| 279 |
If Statements |
| 280 |
************* |
| 281 |
|
| 282 |
* When the ``if``, ``elsif`` or ``else`` keywords fit on the |
| 283 |
same line with the condition and the ``then`` keyword, then the |
| 284 |
statement is formatted as follows: |
| 285 |
|
| 286 |
.. index:: Alignment (in an if statement) |
| 287 |
|
| 288 |
.. code-block:: ada |
| 289 |
|
| 290 |
if condition then |
| 291 |
... |
| 292 |
elsif condition then |
| 293 |
... |
| 294 |
else |
| 295 |
... |
| 296 |
end if; |
| 297 |
|
| 298 |
When the above layout is not possible, ``then`` should be aligned |
| 299 |
with ``if``, and conditions should preferably be split before an |
| 300 |
``and`` or ``or`` keyword a follows: |
| 301 |
|
| 302 |
.. code-block:: ada |
| 303 |
|
| 304 |
if long_condition_that_has_to_be_split |
| 305 |
and then continued_on_the_next_line |
| 306 |
then |
| 307 |
... |
| 308 |
end if; |
| 309 |
|
| 310 |
The ``elsif``, ``else`` and ``end if`` always line up with |
| 311 |
the ``if`` keyword. The preferred location for splitting the line |
| 312 |
is before ``and`` or ``or``. The continuation of a condition is |
| 313 |
indented with two spaces or as many as needed to make nesting clear. |
| 314 |
As an exception, if conditions are closely related either of the |
| 315 |
following is allowed: |
| 316 |
|
| 317 |
.. code-block:: ada |
| 318 |
|
| 319 |
if x = lakdsjfhlkashfdlkflkdsalkhfsalkdhflkjdsahf |
| 320 |
or else |
| 321 |
x = asldkjhalkdsjfhhfd |
| 322 |
or else |
| 323 |
x = asdfadsfadsf |
| 324 |
then |
| 325 |
... |
| 326 |
end if; |
| 327 |
|
| 328 |
if x = lakdsjfhlkashfdlkflkdsalkhfsalkdhflkjdsahf or else |
| 329 |
x = asldkjhalkdsjfhhfd or else |
| 330 |
x = asdfadsfadsf |
| 331 |
then |
| 332 |
... |
| 333 |
end if; |
| 334 |
|
| 335 |
* Conditions should use short-circuit forms ( ``and then``, |
| 336 |
``or else`` ), except when the operands are boolean variables |
| 337 |
or boolean constants. |
| 338 |
|
| 339 |
.. index:: Short-circuit forms |
| 340 |
|
| 341 |
* Complex conditions in ``if`` statements are indented two characters: |
| 342 |
|
| 343 |
.. index:: Indentation (in if statements) |
| 344 |
|
| 345 |
.. code-block:: ada |
| 346 |
|
| 347 |
if this_complex_condition |
| 348 |
and then that_other_one |
| 349 |
and then one_last_one |
| 350 |
then |
| 351 |
... |
| 352 |
end if; |
| 353 |
|
| 354 |
There are some cases where complex conditionals can be laid out |
| 355 |
in manners that do not follow these rules to preserve better |
| 356 |
parallelism between branches, e.g. |
| 357 |
|
| 358 |
.. code-block:: ada |
| 359 |
|
| 360 |
if xyz.abc (gef) = 'c' |
| 361 |
or else |
| 362 |
xyz.abc (gef) = 'x' |
| 363 |
then |
| 364 |
... |
| 365 |
end if; |
| 366 |
|
| 367 |
* Every ``if`` block is preceded and followed by a blank line, except |
| 368 |
where it begins or ends a sequence_of_statements. |
| 369 |
|
| 370 |
.. index:: Blank lines (in an if statement) |
| 371 |
|
| 372 |
.. code-block:: ada |
| 373 |
|
| 374 |
A := 5; |
| 375 |
|
| 376 |
if A = 5 then |
| 377 |
null; |
| 378 |
end if; |
| 379 |
|
| 380 |
A := 6; |
| 381 |
|
| 382 |
Case Statements |
| 383 |
*************** |
| 384 |
|
| 385 |
* Layout is as below. For long ``case`` statements, the extra indentation |
| 386 |
can be saved by aligning the ``when`` clauses with the opening ``case``. |
| 387 |
|
| 388 |
.. code-block:: ada |
| 389 |
|
| 390 |
case expression is |
| 391 |
when condition => |
| 392 |
... |
| 393 |
when condition => |
| 394 |
... |
| 395 |
end case; |
| 396 |
|
| 397 |
Loop Statements |
| 398 |
*************** |
| 399 |
|
| 400 |
* When possible, have ``for`` or ``while`` on one line with the |
| 401 |
condition and the ``loop`` keyword. |
| 402 |
|
| 403 |
.. code-block:: ada |
| 404 |
|
| 405 |
for J in S'Range loop |
| 406 |
... |
| 407 |
end loop; |
| 408 |
|
| 409 |
If the condition is too long, split the condition (see 'If |
| 410 |
statements' above) and align ``loop`` with the ``for`` or |
| 411 |
``while`` keyword. |
| 412 |
|
| 413 |
.. index:: Alignment (in a loop statement) |
| 414 |
|
| 415 |
.. code-block:: ada |
| 416 |
|
| 417 |
while long_condition_that_has_to_be_split |
| 418 |
and then continued_on_the_next_line |
| 419 |
loop |
| 420 |
... |
| 421 |
end loop; |
| 422 |
|
| 423 |
If the loop_statement has an identifier, it is laid out as follows: |
| 424 |
|
| 425 |
.. code-block:: ada |
| 426 |
|
| 427 |
Outer : while not condition loop |
| 428 |
... |
| 429 |
end Outer; |
| 430 |
|
| 431 |
Block Statements |
| 432 |
**************** |
| 433 |
|
| 434 |
* The ``declare`` (optional), ``begin`` and ``end`` words |
| 435 |
are aligned, except when the block_statement is named. There |
| 436 |
is a blank line before the ``begin`` keyword: |
| 437 |
|
| 438 |
.. index:: Alignment (in a block statement) |
| 439 |
|
| 440 |
.. code-block:: ada |
| 441 |
|
| 442 |
Some_Block : declare |
| 443 |
... |
| 444 |
|
| 445 |
begin |
| 446 |
... |
| 447 |
end Some_Block; |
| 448 |
|
| 449 |
Subprograms |
| 450 |
----------- |
| 451 |
|
| 452 |
Subprogram Declarations |
| 453 |
*********************** |
| 454 |
|
| 455 |
* Do not write the ``in`` for parameters. |
| 456 |
|
| 457 |
.. code-block:: ada |
| 458 |
|
| 459 |
function Length (S : String) return Integer; |
| 460 |
|
| 461 |
* When the declaration line for a procedure or a function is too long to fit |
| 462 |
the entire declaration (including the keyword procedure or function) on a |
| 463 |
single line, then fold it, putting a single parameter on a line, aligning |
| 464 |
the colons, as in: |
| 465 |
|
| 466 |
.. code-block:: ada |
| 467 |
|
| 468 |
procedure Set_Heading |
| 469 |
(Source : String; |
| 470 |
Count : Natural; |
| 471 |
Pad : Character := Space; |
| 472 |
Fill : Boolean := True); |
| 473 |
|
| 474 |
In the case of a function, if the entire spec does not fit on one line, then |
| 475 |
the return may appear after the last parameter, as in: |
| 476 |
|
| 477 |
.. code-block:: ada |
| 478 |
|
| 479 |
function Head |
| 480 |
(Source : String; |
| 481 |
Count : Natural; |
| 482 |
Pad : Character := Space) return String; |
| 483 |
|
| 484 |
Or it may appear on its own as a separate line. This form is preferred when |
| 485 |
putting the return on the same line as the last parameter would result in |
| 486 |
an overlong line. The return type may optionally be aligned with the types |
| 487 |
of the parameters (usually we do this aligning if it results only in a small |
| 488 |
number of extra spaces, and otherwise we don't attempt to align). So two |
| 489 |
alternative forms for the above spec are: |
| 490 |
|
| 491 |
.. code-block:: ada |
| 492 |
|
| 493 |
function Head |
| 494 |
(Source : String; |
| 495 |
Count : Natural; |
| 496 |
Pad : Character := Space) |
| 497 |
return String; |
| 498 |
|
| 499 |
function Head |
| 500 |
(Source : String; |
| 501 |
Count : Natural; |
| 502 |
Pad : Character := Space) |
| 503 |
return String; |
| 504 |
|
| 505 |
Subprogram Bodies |
| 506 |
***************** |
| 507 |
|
| 508 |
* Function and procedure bodies should usually be sorted alphabetically. Do |
| 509 |
not attempt to sort them in some logical order by functionality. For a |
| 510 |
sequence of subprogram specs, a general alphabetical sorting is also |
| 511 |
usually appropriate, but occasionally it makes sense to group by major |
| 512 |
function, with appropriate headers. |
| 513 |
|
| 514 |
* All subprograms have a header giving the function name, with the following |
| 515 |
format: |
| 516 |
|
| 517 |
.. code-block:: ada |
| 518 |
|
| 519 |
----------------- |
| 520 |
-- My_Function -- |
| 521 |
----------------- |
| 522 |
|
| 523 |
procedure My_Function is |
| 524 |
begin |
| 525 |
... |
| 526 |
end My_Function; |
| 527 |
|
| 528 |
Note that the name in the header is preceded by a single space, |
| 529 |
not two spaces as for other comments. These headers are used on |
| 530 |
nested subprograms as well as outer level subprograms. They may |
| 531 |
also be used as headers for sections of comments, or collections |
| 532 |
of declarations that are related. |
| 533 |
|
| 534 |
* Every subprogram body must have a preceding subprogram_declaration, |
| 535 |
which includes proper client documentation so that you do not need to |
| 536 |
read the subprogram body in order to understand what the subprogram does and |
| 537 |
how to call it. All subprograms should be documented, without exceptions. |
| 538 |
|
| 539 |
.. index:: Blank lines (in subprogram bodies) |
| 540 |
|
| 541 |
* A sequence of declarations may optionally be separated from the following |
| 542 |
begin by a blank line. Just as we optionally allow blank lines in general |
| 543 |
between declarations, this blank line should be present only if it improves |
| 544 |
readability. Generally we avoid this blank line if the declarative part is |
| 545 |
small (one or two lines) and the body has no blank lines, and we include it |
| 546 |
if the declarative part is long or if the body has blank lines. |
| 547 |
|
| 548 |
* If the declarations in a subprogram contain at least one nested |
| 549 |
subprogram body, then just before the ``begin`` of the enclosing |
| 550 |
subprogram, there is a comment line and a blank line: |
| 551 |
|
| 552 |
.. code-block:: ada |
| 553 |
|
| 554 |
-- Start of processing for Enclosing_Subprogram |
| 555 |
|
| 556 |
begin |
| 557 |
... |
| 558 |
end Enclosing_Subprogram; |
| 559 |
|
| 560 |
* When nested subprograms are present, variables that are referenced by any |
| 561 |
nested subprogram should precede the nested subprogram specs. For variables |
| 562 |
that are not referenced by nested procedures, the declarations can either also |
| 563 |
be before any of the nested subprogram specs (this is the old style, more |
| 564 |
generally used). Or then can come just before the begin, with a header. The |
| 565 |
following example shows the two possible styles: |
| 566 |
|
| 567 |
.. code-block:: ada |
| 568 |
|
| 569 |
procedure Style1 is |
| 570 |
Var_Referenced_In_Nested : Integer; |
| 571 |
Var_Referenced_Only_In_Style1 : Integer; |
| 572 |
|
| 573 |
proc Nested; |
| 574 |
-- Comments ... |
| 575 |
|
| 576 |
------------ |
| 577 |
-- Nested -- |
| 578 |
------------ |
| 579 |
|
| 580 |
procedure Nested is |
| 581 |
begin |
| 582 |
... |
| 583 |
end Nested; |
| 584 |
|
| 585 |
-- Start of processing for Style1 |
| 586 |
|
| 587 |
begin |
| 588 |
... |
| 589 |
end Style1; |
| 590 |
|
| 591 |
procedure Style2 is |
| 592 |
Var_Referenced_In_Nested : Integer; |
| 593 |
|
| 594 |
proc Nested; |
| 595 |
-- Comments ... |
| 596 |
|
| 597 |
------------ |
| 598 |
-- Nested -- |
| 599 |
------------ |
| 600 |
|
| 601 |
procedure Nested is |
| 602 |
begin |
| 603 |
... |
| 604 |
end Nested; |
| 605 |
|
| 606 |
-- Local variables |
| 607 |
|
| 608 |
Var_Referenced_Only_In_Style2 : Integer; |
| 609 |
|
| 610 |
-- Start of processing for Style2 |
| 611 |
|
| 612 |
begin |
| 613 |
... |
| 614 |
end Style2; |
| 615 |
|
| 616 |
For new code, we generally prefer Style2, but we do not insist on |
| 617 |
modifying all legacy occurrences of Style1, which is still much |
| 618 |
more common in the sources. |
| 619 |
|
| 620 |
Packages and Visibility Rules |
| 621 |
----------------------------- |
| 622 |
|
| 623 |
* All program units and subprograms have their name at the end: |
| 624 |
|
| 625 |
.. code-block:: ada |
| 626 |
|
| 627 |
package P is |
| 628 |
... |
| 629 |
end P; |
| 630 |
|
| 631 |
* We will use the style of ``use`` -ing ``with`` -ed packages, with |
| 632 |
the context clauses looking like: |
| 633 |
|
| 634 |
.. index:: use clauses |
| 635 |
|
| 636 |
.. code-block:: ada |
| 637 |
|
| 638 |
with A; use A; |
| 639 |
with B; use B; |
| 640 |
|
| 641 |
* Names declared in the visible part of packages should be |
| 642 |
unique, to prevent name clashes when the packages are ``use`` d. |
| 643 |
|
| 644 |
.. index:: Name clash avoidance |
| 645 |
|
| 646 |
.. code-block:: ada |
| 647 |
|
| 648 |
package Entity is |
| 649 |
type Entity_Kind is ...; |
| 650 |
... |
| 651 |
end Entity; |
| 652 |
|
| 653 |
* After the file header comment, the context clause and unit specification |
| 654 |
should be the first thing in a program_unit. |
| 655 |
|
| 656 |
* Preelaborate, Pure and Elaborate_Body pragmas should be added right after the |
| 657 |
package name, indented an extra level and using the parameterless form: |
| 658 |
|
| 659 |
.. code-block:: ada |
| 660 |
|
| 661 |
package Preelaborate_Package is |
| 662 |
pragma Preelaborate; |
| 663 |
... |
| 664 |
end Preelaborate_Package; |
| 665 |
|
| 666 |
Program Structure and Compilation Issues |
| 667 |
---------------------------------------- |
| 668 |
|
| 669 |
* Every GNAT source file must be compiled with the ``-gnatg`` |
| 670 |
switch to check the coding style. |
| 671 |
(Note that you should look at |
| 672 |
style.adb to see the lexical rules enforced by ``-gnatg`` ). |
| 673 |
|
| 674 |
.. index:: -gnatg option (to gcc) |
| 675 |
.. index:: style.adb file |
| 676 |
|
| 677 |
* Each source file should contain only one compilation unit. |
| 678 |
|
| 679 |
* Filenames should be 8 or fewer characters, followed by the ``.adb`` |
| 680 |
extension for a body or ``.ads`` for a spec. |
| 681 |
|
| 682 |
.. index:: File name length |
| 683 |
|
| 684 |
* Unit names should be distinct when 'krunch'ed to 8 characters |
| 685 |
(see krunch.ads) and the filenames should match the unit name, |
| 686 |
except that they are all lower case. |
| 687 |
|
| 688 |
.. index:: krunch.ads file |
| 689 |
|
| 690 |
.. toctree:: |
| 691 |
share/gnu_free_documentation_license |