Ada 95 Quality and Style Guide Chapter 3

Chapter 3: Readability - TOC - 3.3 COMMENTS

3.3.7 Marker Comments


  • Use pagination markers to mark program unit boundaries (see Guideline 2.1.7).
  • Repeat the unit name in a comment to mark the begin of a package body, subprogram body, task body, or block if the begin is preceded by declarations.
  • For long or heavily nested if and case statements, mark the end of the statement with a comment summarizing the condition governing the statement.
  • For long or heavily nested if statements, mark the else part with a comment summarizing the conditions governing this portion of the statement.

  • example
    if    A_Found then
    elsif B_Found then
    else  -- A and B were both not found
       if Count = Max then
       end if;
    end if;  -- A_Found
    package body Abstract_Strings is
       procedure Concatenate (...) is
       end Concatenate;
    begin  -- Abstract_Strings
    end Abstract_Strings;


    Marker comments emphasize the structure of code and make it easier to scan. They can be lines that separate sections of code or descriptive tags for a construct. They help the reader resolve questions about the current position in the code. This is more important for large units than for small ones. A short marker comment fits on the same line as the reserved word with which it is associated. Thus, it adds information without clutter.

    The if, elsif, else, and end if of an if statement are often separated by long sequences of statements, sometimes involving other if statements. As shown in the first example, marker comments emphasize the association of the keywords of the same statement over a great visual distance. Marker comments are not necessary with the block statement and loop statement because the syntax of these statements allows them to be named with the name repeated at the end. Using these names is better than using marker comments because the compiler verifies that the names at the beginning and end match.

    The sequence of statements of a package body is often very far from the first line of the package. Many subprogram bodies, each containing many begin lines, may occur first. As shown in the second example, the marker comment emphasizes the association of the begin with the package.


    Repeating names and noting conditional expressions clutters the code if overdone. It is visual distance, especially page breaks, that makes marker comments beneficial.

    < Previous Page Search Contents Index Next Page >
    1 2 3 4 5 6 7 8 9 10 11
    Appendix References Bibliography