Chapter 3: Readability - TOC - 3.3 COMMENTS

3.3.7 Marker Comments

guideline

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
   begin
      ...
   end Concatenate;
   ---------------------------------------------------------------------
   ...
begin  -- Abstract_Strings
   ...
end Abstract_Strings;
------------------------------------------------------------------------

rationale

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.

notes

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