Code Complete, 2nd Edition

Key Points

• The question of whether to comment is a legitimate one. Done poorly, commenting is a waste of time and sometimes harmful. Done well, commenting is worthwhile.

• The source code should contain most of the critical information about the program. As long as the program is running, the source code is more likely than any other resource to be kept current, and it's useful to have important information bundled with the code.

• Good code is its own best documentation. If the code is bad enough to require extensive comments, try first to improve the code so that it doesn't need extensive comments.

• Comments should say things about the code that the code can't say about itself—at the summary level or the intent level.

• Some commenting styles require a ...