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.
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?
Visual Basic example of poorly indented comments
Example 31-58.
For transactionId = 1 To totalTransactions ...
Get Code Complete, 2nd Edition now with the O’Reilly learning platform.
O’Reilly members experience books, live events, courses curated by job role, and more from O’Reilly and nearly 200 top publishers.
