Chapter 2: Source Code Presentation - TOC - 2.1 CODE FORMATTING

2.1.7 Pagination

guideline

Highlight the top of each package or task specification, the top of each program unit body, and the end statement of each program unit.

instantiation

Specifically, it is recommended that you:

- Use file prologues, specification headers, and body headers to highlight those structures as recommended in Guideline 3.3.
- Use a line of dashes, beginning at the same column as the current indentation to highlight the definition of nested units embedded in a declarative part. Insert the line of dashes immediately before and immediately after the definition.
- If two dashed lines are adjacent, omit the longer of the two.

example

    with Basic_Types;
    package body SPC_Numeric_Types is
       -------------------------------------------------------
       function Max
             (Left  : in     Basic_Types.Tiny_Integer;
              Right : in     Basic_Types.Tiny_Integer)
             return Basic_Types.Tiny_Integer is
       begin
          if Right < Left then
             return Left;
          else
             return Right;
          end if;
       end Max;
       -------------------------------------------------------
       function Min
             (Left  : in     Basic_Types.Tiny_Integer;
              Right : in     Basic_Types.Tiny_Integer)
             return Basic_Types.Tiny_Integer is
       begin
          if Left < Right then
             return Left;
          else
             return Right;
          end if;
       end Min;
       -------------------------------------------------------
       use Basic_Types;
    begin  -- SPC_Numeric_Types
       Max_Tiny_Integer := Min(System_Max, Local_Max);
       Min_Tiny_Integer := Max(System_Min, Local_Min);
       -- ...
    end SPC_Numeric_Types;

rationale

It is easy to overlook parts of program units that are not visible on the current page or screen. The page lengths of presentation hardware and software vary widely. By clearly marking the program's logical page boundaries (e.g., with a dashed line), you enable a reader to quickly check whether all of a program unit is visible. Such pagination also makes it easier to scan a large file quickly, looking for a particular program unit.

exceptions

This guideline does not address code layout on the physical "page" because the dimensions of such pages vary widely and no single guideline is appropriate.

automation notes

The guidelines in this section are easily enforced with an automatic code formatter.