aboutsummaryrefslogtreecommitdiff
path: root/gcc/ada/gnat-style.texi
blob: 50adaabc993e07fb114dde5794103cbe07eea655 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
\input texinfo   @c -*-texinfo-*-
@c %**start of header

@c oooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooo
@c                                                                            o
@c                           GNAT DOCUMENTATION                               o
@c                                                                            o
@c                     G N A T   C O D I N G   S T Y L E                      o
@c                                                                            o
@c                     Copyright (C) 1992-2012, AdaCore                       o
@c                                                                            o
@c oooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooo

@setfilename gnat-style.info

@copying
Copyright @copyright{} 1992-2012, AdaCore

Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.3 or
any later version published by the Free Software Foundation; with no
Invariant Sections, with no Front-Cover Texts and with no Back-Cover
Texts.  A copy of the license is included in the section entitled
``GNU Free Documentation License''.
@end copying

@settitle GNAT Coding Style
@setchapternewpage odd

@include gcc-common.texi

@dircategory Software development
@direntry
* gnat-style: (gnat-style).      GNAT Coding Style
@end direntry

@macro syntax{element}
@t{\element\}
@end macro
@c %**end of header

@titlepage
@titlefont{GNAT Coding Style:}
@sp 1
@title A Guide for GNAT Developers
@subtitle GNAT, The GNU Ada Compiler
@versionsubtitle
@author Ada Core Technologies, Inc.
@page
@vskip 0pt plus 1filll

@insertcopying
@end titlepage

@raisesections

@node    Top,       General,         , (dir)
@comment node-name, next,    previous, up

@ifnottex
@noindent
GNAT Coding Style@*
A Guide for GNAT Developers
@sp 2
@noindent
GNAT, The GNU Ada Compiler@*

@noindent
@insertcopying
@end ifnottex


@menu
* General::
* Lexical Elements::
* Declarations and Types::
* Expressions and Names::
* Statements::
* Subprograms::
* Packages::
* Program Structure::
* GNU Free Documentation License::
* Index::
@end menu

@c  -------------------------------------------------------------------------
@node    General, Lexical Elements, Top, Top
@section General
@c  -------------------------------------------------------------------------

@noindent
Most of GNAT is written in Ada using a consistent style to ensure
readability of the code.  This document has been written to help
maintain this consistent style, while having a large group of developers
work on the compiler.

For the coding style in the C parts of the compiler and run time,
see the GNU Coding Guidelines.

This document is structured after the @cite{Ada Reference Manual}.
Those familiar with that document should be able to quickly
lookup style rules for particular constructs.


@c  -------------------------------------------------------------------------
@node    Lexical Elements, Declarations and Types, General, Top
@section Lexical Elements
@c  -------------------------------------------------------------------------
@cindex Lexical elements

@subsection Character Set and Separators
@c  -------------------------------------------------------------------------
@cindex Character set
@cindex ASCII
@cindex Separators
@cindex End-of-line
@cindex Line length
@cindex Indentation

@itemize @bullet
@item
The character set used should be plain 7-bit ASCII@.
The only separators allowed are space and the end-of-line sequence.
No other control character or format effector (such as @code{HT},
@code{VT}, @code{FF})
should be used.
The normal end-of-line sequence is used, which may be
@code{LF}, @code{CR/LF} or @code{CR},
depending on the host system.  An optional @code{SUB}
(@code{16#1A#}) may be present as the
last character in the file on hosts using that character as file terminator.

@item
Files that are checked in or distributed should be in host format.

@item
A line should never be longer than 79 characters, not counting the line
separator.

@item
Lines must not have trailing blanks.

@item
Indentation is 3 characters per level for @code{if} statements, loops, and
@code{case} statements.
For exact information on required spacing between lexical
elements, see file @file{style.adb}.
@cindex @file{style.adb} file
@end itemize


@subsection Identifiers
@c  -------------------------------------------------------------------------
@itemize @bullet
@cindex Identifiers

@item
Identifiers will start with an upper case letter, and each letter following
an underscore will be upper case.
@cindex Casing (for identifiers)
Short acronyms may be all upper case.
All other letters are lower case.
An exception is for identifiers matching a foreign language.  In particular,
we use all lower case where appropriate for C@.

@item
Use underscores to separate words in an identifier.
@cindex Underscores

@item Try to limit your use of abbreviations in identifiers.
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.  An
example is the @code{ALI} word which stands for Ada Library
Information and is by convention always written in upper-case when
used in entity names.

@smallexample @c adanocomment
       procedure Find_ALI_Files;
@end smallexample

@item
Don't use the variable name @code{I}, use @code{J} instead; @code{I} is too
easily confused with @code{1} in some fonts.  Similarly don't use the
variable @code{O}, which is too easily mistaken for the number @code{0}.
@end itemize

@subsection Numeric Literals
@c  -------------------------------------------------------------------------
@cindex Numeric literals

@itemize @bullet
@item
Numeric literals should include underscores where helpful for
readability.
@cindex Underscores

@smallexample
      1_000_000
      16#8000_0000#
      3.14159_26535_89793_23846
@end smallexample
@end itemize

@subsection Reserved Words
@c  -------------------------------------------------------------------------
@cindex Reserved words

@itemize @bullet
@item
Reserved words use all lower case.
@cindex Casing (for reserved words)

@smallexample @c adanocomment
       return else
@end smallexample

@item
The words @code{Access}, @code{Delta} and @code{Digits} are
capitalized when used as @syntax{attribute_designator}.
@end itemize

@subsection Comments
@c  -------------------------------------------------------------------------
@cindex Comments

@itemize @bullet
@item
A comment starts with @code{--} followed by two spaces.
The only exception to this rule (i.e.@: one space is tolerated) is when the
comment ends with a single space followed by @code{--}.
It is also acceptable to have only one space between @code{--} and the start
of the comment when the comment is at the end of a line,
after some Ada code.

@item
Every sentence in a comment should start with an upper-case letter (including
the first letter of the comment).
@cindex Casing (in comments)

@item
When declarations are commented with ``hanging'' comments, i.e.@:
comments after the declaration, there is no blank line before the
comment, and if it is absolutely necessary to have blank lines within
the comments, e.g. to make paragraph separations within a single comment,
these blank lines @emph{do} have a @code{--} (unlike the
normal rule, which is to use entirely blank lines for separating
comment paragraphs).  The comment starts at same level of indentation
as code it is commenting.
@cindex Blank lines (in comments)
@cindex Indentation

@smallexample @c adanocomment
       z : Integer;
       --  Integer value for storing value of z
       --
       --  The previous line was a blank line.
@end smallexample

@item
Comments that are dubious or incomplete, or that comment on possibly
wrong or incomplete code, should be preceded or followed by @code{???}@.

@item
Comments in a subprogram body must generally be surrounded by blank lines.
An exception is a comment that follows a line containing a single keyword
(@code{begin}, @code{else}, @code{loop}):

@smallexample @c adanocomment
@group
       begin
          --  Comment for the next statement

          A := 5;

          --  Comment for the B statement

          B := 6;
       end;
@end group
@end smallexample

@item
In sequences of statements, comments at the end of the lines should be
aligned.
@cindex Alignment (in comments)

@smallexample @c adanocomment
        My_Identifier := 5;      --  First comment
        Other_Id := 6;           --  Second comment
@end smallexample

@item
Short comments that fit on a single line are @emph{not} ended with a
period.  Comments taking more than a line are punctuated in the normal
manner.

@item
Comments should focus on @emph{why} instead of @emph{what}.
Descriptions of what subprograms do go with the specification.

@item
Comments describing a subprogram spec should specifically mention the
formal argument names.  General rule: write a comment that does not
depend on the names of things.  The names are supplementary, not
sufficient, as comments.

@item
@emph{Do not} put two spaces after periods in comments.
@end itemize

@c  -------------------------------------------------------------------------
@node    Declarations and Types, Expressions and Names, Lexical Elements,Top
@section Declarations and Types
@c  -------------------------------------------------------------------------
@cindex Declarations and Types

@itemize @bullet
@item
In entity declarations, colons must be surrounded by spaces.  Colons
should be aligned.
@cindex Alignment (in declarations)

@smallexample @c adanocomment
        Entity1   : Integer;
        My_Entity : Integer;
@end smallexample

@item
Declarations should be grouped in a logical order.
Related groups of declarations may be preceded by a header comment.

@item
All local subprograms in a subprogram or package body should be declared
before the first local subprogram body.

@item
Do not declare local entities that hide global entities.
@cindex Hiding of outer entities

@item
Do not declare multiple variables in one declaration that spans lines.
Start a new declaration on each line, instead.

@item
The @syntax{defining_identifier}s of global declarations serve as
comments of a sort.  So don't choose terse names, but look for names
that give useful information instead.

@item
Local names can be shorter, because they are used only within
one context, where comments explain their purpose.

@item
When starting an initialization or default expression on the line that follows
the declaration line, use 2 characters for indentation.

@smallexample @c adanocomment
        Entity1 : Integer :=
          Function_Name (Parameters, For_Call);
@end smallexample

@item
If an initialization or default expression needs to be continued on subsequent
lines, the continuations should be indented from the start of the expression.

@smallexample @c adanocomment
        Entity1 : Integer := Long_Function_Name
                               (parameters for call);
@end smallexample

@end itemize


@c  -------------------------------------------------------------------------
@node    Expressions and Names, Statements, Declarations and Types, Top
@section Expressions and Names
@c  -------------------------------------------------------------------------
@cindex Expressions and names

@itemize @bullet

@item
Every operator must be surrounded by spaces. An exception is that
this rule does not apply to the exponentiation operator, for which
there are no specific layout rules. The reason for this exception
is that sometimes it makes clearer reading to leave out the spaces
around exponentiation.
@cindex Operators

@smallexample @c adanocomment
       E := A * B**2 + 3 * (C - D);
@end smallexample

@item
Use parentheses where they clarify the intended association of operands
with operators:
@cindex Parenthesization of expressions
@smallexample @c adanocomment
       (A / B) * C
@end smallexample
@end itemize

@c  -------------------------------------------------------------------------
@node    Statements, Subprograms, Expressions and Names, Top
@section Statements
@c  -------------------------------------------------------------------------
@cindex Statements

@subsection Simple and Compound Statements
@c  -------------------------------------------------------------------------
@cindex Simple and compound statements

@itemize @bullet
@item
Use only one statement or label per line.
@item
A longer @syntax{sequence_of_statements} may be divided in logical
groups or separated from surrounding code using a blank line.
@end itemize

@subsection If Statements
@c  -------------------------------------------------------------------------
@cindex @code{if} statement

@itemize @bullet
@item
When the @code{if}, @code{elsif} or @code{else} keywords fit on the
same line with the condition and the @code{then} keyword, then the
statement is formatted as follows:
@cindex Alignment (in an @code{if} statement)

@smallexample @c adanocomment
@group
        if @var{condition} then
           ...
        elsif @var{condition} then
           ...
        else
           ...
        end if;
@end group
@end smallexample

@noindent
When the above layout is not possible, @code{then} should be aligned
with @code{if}, and conditions should preferably be split before an
@code{and} or @code{or} keyword a follows:

@smallexample @c adanocomment
@group
        if @var{long_condition_that_has_to_be_split}
          and then @var{continued_on_the_next_line}
        then
           ...
        end if;
@end group
@end smallexample

@noindent
The @code{elsif}, @code{else} and @code{end if} always line up with
the @code{if} keyword.  The preferred location for splitting the line
is before @code{and} or @code{or}.  The continuation of a condition is
indented with two spaces or as many as needed to make nesting clear.
As an exception, if conditions are closely related either of the
following is allowed:

@smallexample
@group
     if x = lakdsjfhlkashfdlkflkdsalkhfsalkdhflkjdsahf
          or else
        x = asldkjhalkdsjfhhfd
          or else
        x = asdfadsfadsf
     then
       ...
     end if;
@end group

@group
     if x = lakdsjfhlkashfdlkflkdsalkhfsalkdhflkjdsahf or else
        x = asldkjhalkdsjfhhfd                         or else
        x = asdfadsfadsf
     then
       ...
     end if;
@end group
@end smallexample

@item
Conditions should use short-circuit forms (@code{and then},
@code{or else}), except when the operands are boolean variables
or boolean constants.
@cindex Short-circuit forms

@item
Complex conditions in @code{if} statements are indented two characters:
@cindex Indentation (in @code{if} statements)

@smallexample @c adanocomment
@group
      if @var{this_complex_condition}
        and then @var{that_other_one}
        and then @var{one_last_one}
      then
         ...
      end if;
@end group
@end smallexample

@noindent
There are some cases where complex conditionals can be laid out
in manners that do not follow these rules to preserve better
parallelism between branches, e.g.

@smallexample @c adanocomment
@group
      if xyz.abc (gef) = 'c'
           or else
         xyz.abc (gef) = 'x'
      then
         ...
      end if;
@end group
@end smallexample


@item
Every @code{if} block is preceded and followed by a blank line, except
where it begins or ends a @syntax{sequence_of_statements}.
@cindex Blank lines (in an @code{if} statement)

@smallexample @c adanocomment
@group
        A := 5;

        if A = 5 then
           null;
        end if;

        A := 6;
@end group
@end smallexample
@end itemize

@subsection Case Statements
@cindex @code{case} statements

@itemize @bullet
@item
Layout is as below.  For long @code{case} statements, the extra indentation
can be saved by aligning the @code{when} clauses with the opening @code{case}.

@smallexample @c adanocomment
@group
       case @var{expression} is
          when @var{condition} =>
             ...
          when @var{condition} =>
             ...
       end case;
@end group
@end smallexample
@end itemize

@subsection Loop Statements
@cindex Loop statements

@itemize @bullet
@item
When possible, have @code{for} or @code{while} on one line with the
condition and the @code{loop} keyword.

@smallexample @c adanocomment
@group
       for J in S'Range loop
          ...
       end loop;
@end group
@end smallexample

@noindent
If the condition is too long, split the condition (see ``If
statements'' above) and align @code{loop} with the @code{for} or
@code{while} keyword.
@cindex Alignment (in a loop statement)

@smallexample @c adanocomment
@group
      while @var{long_condition_that_has_to_be_split}
        and then @var{continued_on_the_next_line}
      loop
         ...
      end loop;
@end group
@end smallexample

@noindent
If the @syntax{loop_statement} has an identifier, it is laid out as follows:

@smallexample @c adanocomment
@group
      Outer : while not @var{condition} loop
         ...
      end Outer;
@end group
@end smallexample
@end itemize

@subsection Block Statements
@cindex Block statement

@itemize @bullet
@item
The @code{declare} (optional), @code{begin} and @code{end} words
are aligned, except when the @syntax{block_statement} is named.  There
is a blank line before the @code{begin} keyword:
@cindex Alignment (in a block statement)

@smallexample @c adanocomment
@group
      Some_Block : declare
         ...

      begin
         ...
      end Some_Block;
@end group
@end smallexample

@end itemize

@c  -------------------------------------------------------------------------
@node    Subprograms, Packages, Statements, Top
@section Subprograms
@c  -------------------------------------------------------------------------
@cindex Subprograms

@subsection Subprogram Declarations
@c  -------------------------------------------------------------------------
@itemize @bullet

@item
Do not write the @code{in} for parameters.

@smallexample @c adanocomment
      function Length (S : String) return Integer;
@end smallexample

@item
When the declaration line for a procedure or a function is too long to fit
the entire declaration (including the keyword procedure or function) on a
single line, then fold it, putting a single parameter on a line, aligning
the colons, as in:

@smallexample @c adanocomment
@group
     procedure Set_Heading
       (Source : String;
        Count  : Natural;
        Pad    : Character := Space;
        Fill   : Boolean   := True);
@end group
@end smallexample

@noindent
In the case of a function, if the entire spec does not fit on one line, then
the return may appear after the last parameter, as in:

@smallexample @c adanocomment
@group
      function Head
        (Source : String;
         Count  : Natural;
         Pad    : Character := Space) return String;
@end group
@end smallexample

@noindent
Or it may appear on its own as a separate line. This form is preferred when
putting the return on the same line as the last parameter would result in
an overlong line. The return type may optionally be aligned with the types
of the parameters (usually we do this aligning if it results only in a small
number of extra spaces, and otherwise we don't attempt to align). So two
alternative forms for the above spec are:

@smallexample @c adanocomment
@group
      function Head
        (Source : String;
         Count  : Natural;
         Pad    : Character := Space)
         return   String;

      function Head
        (Source : String;
         Count  : Natural;
         Pad    : Character := Space)
         return String;
@end group
@end smallexample

@end itemize

@subsection Subprogram Bodies
@c  -------------------------------------------------------------------------
@cindex Subprogram bodies

@itemize @bullet
@item
Function and procedure bodies should usually be sorted alphabetically. Do
not attempt to sort them in some logical order by functionality. For a
sequence of subprogram specs, a general alphabetical sorting is also
usually appropriate, but occasionally it makes sense to group by major
function, with appropriate headers.

@item
All subprograms have a header giving the function name, with the following
format:

@smallexample @c adanocomment
@group
      -----------------
      -- My_Function --
      -----------------

      procedure My_Function is
      begin
        ...
      end My_Function;
@end group
@end smallexample

@noindent
Note that the name in the header is preceded by a single space,
not two spaces as for other comments. These headers are used on
nested subprograms as well as outer level subprograms. They may
also be used as headers for sections of comments, or collections
of declarations that are related.

@item
Every subprogram body must have a preceding @syntax{subprogram_declaration},
which includes proper client documentation so that you do not need to
read the subprogram body in order to understand what the subprogram does and
how to call it. All subprograms should be documented, without exceptions.

@item
@cindex Blank lines (in subprogram bodies)
A sequence of declarations may optionally be separated from the following
begin by a blank line.  Just as we optionally allow blank lines in general
between declarations, this blank line should be present only if it improves
readability. Generally we avoid this blank line if the declarative part is
small (one or two lines) and the body has no blank lines, and we include it
if the declarative part is long or if the body has blank lines.

@item
If the declarations in a subprogram contain at least one nested
subprogram body, then just before the @code{begin} of the enclosing
subprogram, there is a comment line and a blank line:

@smallexample @c adanocomment
@group
    --  Start of processing for @var{Enclosing_Subprogram}

    begin
      ...
    end @var{Enclosing_Subprogram};
@end group
@end smallexample

@item
When nested subprograms are present, variables that are referenced by any
nested subprogram should precede the nested subprogram specs. For variables
that are not referenced by nested procedures, the declarations can either also
be before any of the nested subprogram specs (this is the old style, more
generally used). Or then can come just before the begin, with a header. The
following example shows the two possible styles:

@smallexample @c adanocomment
@group
    procedure Style1 is
       Var_Referenced_In_Nested      : Integer;
       Var_Referenced_Only_In_Style1 : Integer;

       proc Nested;
       --  Comments ...


       ------------
       -- Nested --
       ------------

       procedure Nested is
       begin
          ...
       end Nested;

    --  Start of processing for Style1

    begin
       ...
    end Style1;

@end group

@group
    procedure Style2 is
       Var_Referenced_In_Nested : Integer;

       proc Nested;
       --  Comments ...

       ------------
       -- Nested --
       ------------

       procedure Nested is
       begin
          ...
       end Nested;

       --  Local variables

       Var_Referenced_Only_In_Style2 : Integer;

    --  Start of processing for Style2

    begin
       ...
    end Style2;

@end group
@end smallexample

@noindent
For new code, we generally prefer Style2, but we do not insist on
modifying all legacy occurrences of Style1, which is still much
more common in the sources.

@end itemize


@c  -------------------------------------------------------------------------
@node    Packages, Program Structure, Subprograms, Top
@section Packages and Visibility Rules
@c  -------------------------------------------------------------------------
@cindex Packages

@itemize @bullet
@item
All program units and subprograms have their name at the end:

@smallexample @c adanocomment
@group
      package P is
         ...
      end P;
@end group
@end smallexample

@item
We will use the style of @code{use}-ing @code{with}-ed packages, with
the context clauses looking like:
@cindex @code{use} clauses

@smallexample @c adanocomment
@group
      with A; use A;
      with B; use B;
@end group
@end smallexample

@item
Names declared in the visible part of packages should be
unique, to prevent name clashes when the packages are @code{use}d.
@cindex Name clash avoidance

@smallexample @c adanocomment
@group
      package Entity is
         type Entity_Kind is ...;
         ...
      end Entity;
@end group
@end smallexample

@item
After the file header comment, the context clause and unit specification
should be the first thing in a @syntax{program_unit}.

@item
Preelaborate, Pure and Elaborate_Body pragmas should be added right after the
package name, indented an extra level and using the parameterless form:

@smallexample @c adanocomment
@group
      package Preelaborate_Package is
         pragma Preelaborate;
         ...
      end Preelaborate_Package;
@end group
@end smallexample

@end itemize

@c  -------------------------------------------------------------------------
@node    Program Structure, GNU Free Documentation License, Packages, Top
@section Program Structure and Compilation Issues
@c  -------------------------------------------------------------------------
@cindex Program structure

@itemize @bullet
@item
Every GNAT source file must be compiled with the @option{-gnatg}
switch to check the coding style.
(Note that you should look at
@file{style.adb} to see the lexical rules enforced by
@option{-gnatg}).
@cindex @option{-gnatg} option (to gcc)
@cindex @file{style.adb} file

@item
Each source file should contain only one compilation unit.

@item
Filenames should be 8 or fewer characters, followed by the @code{.adb}
extension for a body or @code{.ads} for a spec.
@cindex File name length

@item
Unit names should be distinct when ``krunch''ed to 8 characters
(see @file{krunch.ads}) and the filenames should match the unit name,
except that they are all lower case.
@cindex @file{krunch.ads} file
@end itemize


@c **********************************
@c * GNU Free Documentation License *
@c **********************************
@node GNU Free Documentation License,Index, Program Structure, Top
@unnumberedsec GNU Free Documentation License
@set nodefaultgnufreedocumentationlicensenode
@include fdl.texi
@c GNU Free Documentation License
@cindex GNU Free Documentation License

@node Index,,GNU Free Documentation License, Top
@unnumberedsec Index

@printindex cp

@contents

@bye