31.6. Laying Out Comments

Comments done well can greatly enhance a program's readability; comments done poorly can actually hurt it. The layout of comments plays a large role in whether they help or hinder readability.

Cross-Reference

For details on other aspects of comments, see Chapter 32, "Self-Documenting Code."

Indent a comment with its corresponding code Visual indentation is a valuable aid to understanding a program's logical structure, and good comments don't interfere with the visual indentation. For example, what is the logical structure of the routine shown in Listing 31-58?

Visual Basic example of poorly indented comments

Listing 31-58.

For transactionId = 1 To totalTransactions ' get transaction data    GetTransactionType( transactionType )    GetTransactionAmount( transactionAmount ) ' process transaction based on transaction type    If transactionType = Transaction_Sale Then       AcceptCustomerSale( transactionAmount )    Else       If transactionType = Transaction_CustomerReturn Then ' either process return automatically or get manager approval, if  required          If transactionAmount >= MANAGER_APPROVAL_LEVEL Then ' try to get manager approval and then accept or reject the return ' based on whether approval is granted             GetMgrApproval( isTransactionApproved )             If ( isTransactionApproved ) Then                AcceptCustomerReturn( transactionAmount )             Else                RejectCustomerReturn( transactionAmount )             End If          Else ' manager approval not required, so accept return             AcceptCustomerReturn( transactionAmount )          End If       End If    End If Next

In this example, you don't get much of a clue to the logical structure because the comments completely obscure the visual indentation of the code. You might find it hard to believe that anyone ever makes a conscious decision to use such an indentation style, but I've seen it in professional programs and know of at least one textbook that recommends it.

The code shown in Listing 31-59 is exactly the same as that in Listing 31-58, except for the indentation of the comments.

Listing 31-59. Visual Basic example of nicely indented comments

 For transactionId = 1 To totalTransactions    ' get transaction data    GetTransactionType( transactionType )    GetTransactionAmount( transactionAmount )    ' process transaction based on transaction type    If transactionType = Transaction_Sale Then       AcceptCustomerSale( transactionAmount )    Else       If transactionType = Transaction_CustomerReturn Then        ' either process return automatically or get manager approval, if required          If transactionAmount >= MANAGER_APPROVAL_LEVEL Then             ' try to get manager approval and then accept or reject the return             ' based on whether approval is granted             GetMgrApproval( isTransactionApproved )             If ( isTransactionApproved ) Then                AcceptCustomerReturn( transactionAmount )             Else                RejectCustomerReturn( transactionAmount )             End If          Else             ' manager approval not required, so accept return             AcceptCustomerReturn( transactionAmount )          End If       End If    End If Next

In Listing 31-59, the logical structure is more apparent. One study of the effectiveness of commenting found that the benefit of having comments was not conclusive, and the author speculated that it was because they "disrupt visual scanning of the program" (Shneiderman 1980). From these examples, it's obvious that the style of commenting strongly influences whether comments are disruptive.

Set off each comment with at least one blank line If someone is trying to get an overview of your program, the most effective way to do it is to read the comments without reading the code. Setting comments off with blank lines helps a reader scan the code. An example is shown in Listing 31-60:

Listing 31-60. Java example of setting off a comment with a blank line

// comment zero CodeStatementZero; CodeStatementOne; // comment one CodeStatementTwo; CodeStatementThree;

Some people use a blank line both before and after the comment. Two blanks use more display space, but some people think the code looks better than with just one. An example is shown in Listing 31-61:

Listing 31-61. Java example of setting off a comment with two blank lines

// comment zero CodeStatementZero; CodeStatementOne; // comment one CodeStatementTwo; CodeStatementThree;

Unless your display space is at a premium, this is a purely aesthetic judgment and you can make it accordingly. In this, as in many other areas, the fact that a convention exists is more important than the convention's specific details.