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.
For details on other aspects of comments, see Chapter 32.
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 Example 31-58?
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 Example 31-59 is exactly the same as that in Example 31-58, except for the indentation of the comments.
Example 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 Example 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 Example 31-60:
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 Example 31-61:
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.
3.21.106.7