3.6.1 Comment As You Code

It is very difficult to make time to document your code after you have finished writing your program. Psychologically, you want to (and often need to) move on to the next programming challenge after you get a program working.

You may also have a harder time writing your comments once you have put some distance between your brain cells and those lines of code. Why exactly did you write the loop that way? Where precisely is the value of that global variable set? Unless you have total recall, post-development documentation can be a real challenge.

The last and perhaps most important reason to write your comments as you write your code is that the resulting code will have fewer bugs and (independent of the comments themselves) be easier to understand.

When you write a comment you (theoretically) explain what your code is meant to accomplish. If you find it difficult to come up with that explanation, there is a good chance that you lack a full understanding of what the program does or should do.

The effort that you make to come up with the right comment will certainly improve your comprehension, and may also result in code correction. In this sense, good inline documentation can be as beneficial as a review of your code by a peer. In both cases, the explanation will reveal important information about your program.

3.6.2 Explain the Why -- Not the How -- of Your Program

What do you think of the comments in the following Oracle Forms trigger code?

-- If the total compensation is more than the maximum...
IF :employee.total_comp > maximum_salary
THEN
   -- Inform the user of the problem.
   MESSAGE ('Total compensation exceeds maximum. Please re-enter!');

   -- Reset the counter to zero.
   :employee.comp_counter := 0;

   -- Raise the exception to stop trigger processing.
   RAISE FORM_TRIGGER_FAILURE;
END IF;

None of these comments add anything to the comprehension of the code. Each comment simply restates the line of code, which in most cases is self-explanatory.

Avoid adding comments simply so that you can say, "Yes, I documented my code!" Rely as much as possible on the structure and layout of the code itself to express the meaning of the program. Reserve your comments to explain the Why of your code: What business rule is it meant to implement? Why did you need to implement a certain requirement in a certain way?

In addition, use comments to translate internal, computer-language terminology into something meaningful for the application. Suppose you are using Oracle Forms GLOBAL variables to keep track of a list of names entered. Does the following comment explain the purpose of the code or simply restate what the code is doing?

/* Set the number of elements to zero. */
:GLOBAL.num_elements := 0;

Once again, the comment adds no value. Does the next comment offer additional information?

/* Empty the list of names. */
:GLOBAL.num_elements := 0;

This comment actually explains the purpose of the assignment of the global to zero. By setting the number of elements to zero, I will have effectively emptied the list. This comment has translated the "computer lingo" into a description of the effect of the statement. Of course, you would be even better off hiding the fact that you use this particular global variable to empty a list and instead build a procedure as follows:

PROCEDURE empty_list IS
BEGIN
   :GLOBAL.num_elements := 0;
END;

Then to empty a list you would not need any comment at all. You could simply include the statement:

empty_list;

and the meaning would be perfectly clear.

3.6.3 Make Comments Easy to Enter and Maintain

You shouldn't spend a lot of time formatting your comments. You need to develop a style that is clean and easy to read, but also easy to maintain. When you have to change a comment, you shouldn't have to reformat every line in the comment. Lots of fancy formatting is a good indication that you have a high-maintenance documentation style. The following block comment is a maintenance nightmare:

/*
===========================================================
| Parameter          Description                          |
|                                                         |
| company_id         The primary key to company           |
| start_date         Start date used for date range       |
| end_date           End date for date range              |
===========================================================
*/

The right-justified vertical lines and column formatting for the parameters require way too much effort to enter and maintain. What happens if you add a parameter with a very long name? What if you need to write a longer description? A simpler and more maintainable version of this comment might be:

/*
===========================================================
| Parameter - Description
|
| company_id - The primary key to company
| start_date - Start date used for date range
| end_date - End date for date range
===========================================================
*/

I like to use the following format for my block comments:

/*
|| I put the slash-asterisk that starts the comment on a line all by
|| itself. Then I start each line in the comment block with a double
|| vertical bar to highlight the presence of the comment. Finally,
|| I place the asterisk-slash on a line all by itself.
*/

On the negative side, the vertical bars have to be erased whenever I reformat the lines, but that isn't too much of an effort. On the positive side, those vertical bars make it very easy for a programmer who is scanning the left side of the code to pick out the comments.

I put the comment markers on their own lines to increase the whitespace in my program and set off the comment. That way I can avoid "heavy" horizontal lines full of delimiters, such as asterisks or dashes, and avoid having to match the longest line in the comment.

3.6.4 Maintain Indentation

Inline commentary should reinforce the indentation and therefore the logical structure of the program. For example, it is very easy to find the comments in the make_array procedures shown below. I do not use any double-hyphens, so the slash-asterisk sequences stand out nicely. In addition, all comments start in the first column, so I can easily scan down the left-hand side of the program and pick out the documentation:

PROCEDURE make_array (num_rows_in IN INTEGER)
/* Create an array of specified numbers of rows */
IS
/* Handles to Oracle Forms structures */
   col_id GROUPCOLUMN;
   rg_id RECORDGROUP;
BEGIN
/* Create new record group and column */
   rg_id := CREATE_GROUP ('array');
   col_id := ADD_GROUP_COLUMN ('col');
/*
|| Use a loop to create the specified number of rows and
|| set the value in each cell.
*/
   FOR row_index IN 1 .. num_rows_in
   LOOP
/* Create a row at the end of the group to accept data */
      ADD_GROUP_ROW (return_value, END_OF_GROUP);
      FOR col_index IN 1 .. num_columns_in
      LOOP
/* Set the initial value in the cell */
         SET_GROUP_NUMBER_CELL (col_id, row_index, 0);
      END LOOP;
   END LOOP;
END;

The problem with these comments is precisely that they do all start in the first column, regardless of the code they describe. The most glaring example of this formatting "disconnect" comes in the inner loop, repeated below:

      FOR col_index IN 1 .. num_columns_in
      LOOP
/* Set the initial value in the cell */
         SET_GROUP_NUMBER_CELL (col_id, row_index, 0);
      END LOOP;

Your eye follows the three-space indentation very smoothly into the loop and then you are forced to move all the way to the left to pick up the comment. This format disrupts your reading of the code and therefore its readability. The code loses some of its ability to communicate the logical flow "at a glance," because the physical sense of indentation as logical flow is marred by the comments. Finally, you may end up writing full-line comments which are much longer than the code they appear next to, further distorting the code.

Your comments should always be indented at the same level as the code which they describe. Assuming the comments come before the code itself, those lines of descriptive text will initiate the indentation at that logical level, which will also reinforce that structure. The make_array procedure, properly indented, is shown below:

PROCEDURE make_array (num_rows_in IN INTEGER)
/* Create an array of specified numbers of rows */
IS
   /* Handles to Oracle Forms structures */
   col_id GROUPCOLUMN;
   rg_id RECORDGROUP;
BEGIN
   /* Create new record group and column */
   rg_id := CREATE_GROUP ('array');
   col_id := ADD_GROUP_COLUMN ('col');
   /*
   || Use a loop to create the specified number of rows and
   || set the value in each cell.
   */
   FOR row_index IN 1 .. num_rows_in
   LOOP
      /* Create a row at the end of the group to accept data */
      ADD_GROUP_ROW (return_value, END_OF_GROUP);
      FOR col_index IN 1 .. num_columns_in
      LOOP
         /* Set the initial value in the cell */
         SET_GROUP_NUMBER_CELL (col_id, row_index, 0);
      END LOOP;
   END LOOP;
END;

      END LOOP;

   END LOOP;
END;

3.6.5 Comment Declaration Statements

I propose the following simple rule for documenting declaration statements:

Does that sound excessive? Well, I must admit that I do not follow this guideline at all times, but I bet people who read my code wish I had. The declaration of a variable which seems to me to be perfectly clear may be a source of abiding confusion for others. Like many other people, I still have difficulty understanding that what is obvious to me is not necessarily obvious to someone else.

Consider the declaration section in the next example. The commenting style is inconsistent. I use double-hyphens for a two-line comment; then I use the standard block format to provide information about three variables all at once. I provide comments for some variables, but not for others. It's hard to make sense of the various declaration statements:

DECLARE
   -- Assume a maximum string length of 1000 for a line of text.
   text_line VARCHAR2 (1000);
   len_text    NUMBER;
   /*
   || Variables used to keep track of string scan:
   ||    atomic_count - running count of atomics scanned.
   ||    still_scanning - Boolean variable controls WHILE loop.
   */
   atomic_count NUMBER := 1;
   still_scanning BOOLEAN;
BEGIN

Let's recast this declaration section using my proposed guideline: a comment for each declaration statement. In the result shown below, the declaration section is now longer than the first version, but it uses whitespace more effectively. Each declaration has its own comment, set off by a blank line if a single-line comment:

DECLARE
   /* Assume a maximum string length of 1000 for a line of text. */
   text_line VARCHAR2 (1000);

   /* Calculate length of string at time of declaration */
   len_string NUMBER;

   /* Running count of number of atomics scanned */
   atomic_count NUMBER := 1;

   /* Boolean variable that controls WHILE loop */
   still_scanning BOOLEAN ;
BEGIN