Code Complete by Steve McConnell : Chapter 19

The author in this chapter focuses on documentation. The author cites a study saying that two-thirds of the total effort on large project goes into creating documentation, rather than source code. The author discusses two kinds of documentation:

• Unit development folders(UDF)/Software development folders(SDF): It is an informal document containing notes used by a developer during construction. It provides details of design decisions which are not documented elsewhere.
• Detailed Design Document: This is a low-level design document describing module-level or routine-level design decisions, the alternatives and the reasons for selecting the approach.
  

The author provides an example of poorly documented and coded routine and modifies it to make it better readable and understandable. The author then provides a checklist in terms guidelines for coding routines, data names, data organization, control, layout and design to make the code self-documented.

The author then provides a conversation between a set of programmers, some of them in favour of commenting the code and some of them against. The author then enlists five categories of comments:

1. Repeat of the code:
2. Explanation of the code: Explanatory comments are used to explain complicated, tricky or sensitive pieces of code. It is better to improve the code and then use summary or intent comments.
3. Marker in the code: It is used to indicate some work not done.
4. Summary of the code: It summarizes several lines of code in one sentence.
5. Description of code's intent:
   

The author then discusses how to produce and maintain comments efficiently. The author explains that the two main reasons it takes a lot of time to write comments is if the commenting style is very time consuming or the programmer is not understanding the program correctly and is not finding words to accurately describe the program. The author provides three examples of fancy commenting styles which are hard to maintain and discourage modification. The author emphasizes on using PDL-to-code process or to comment as you go to reduce commenting time.

The author then provides some guidelines on commenting techniques as below:

1. Avoid comments which use abbreviations you have created.
2. Avoid end-line comments: The amount of space available at the end of the line is very small and forces the programmer to put cryptic comment which doesn't serve any purpose and end up being repeat of the code. Single end-line comment for multiple lines of source code creates confusion as to whether the comment applies to a single statement or a bunch of statements.
   
3. The author provides a set of possible cases where end-line comment is useful:
• Annotate data declarations
• Maintenance notes like bug number fixed by a change
  
• Mark end of blocks
  
4. Paragraph comments should focus on why and not on how. Let code focus on how.
5. Comments should prepare the reader for the code that follows.
6. Make every comment count.
7. Surprises in code should be documented.
8. Avoid abbreviations.
9. Differentiate between major and minor comments: The author provides several ways like underlining, difference in CAPS and ellipses to achieve this.
   
10. Comment anything that is a workaround for an error or an undocumented feature in a language or environment.
11. Justify any violations of good programming style.
12. Instead of commenting tricky code, rewrite it.
13. Comment units of numeric data and their range of values.
14. Document global data.
15. Put a comment before each block and after each control structure.

The author then provides guidelines to comment routines:

1. Describe each comment at the top of the routine in one or two statements.
2. Document input and output variables where they are declared.
3. Clearly differentiate between input and output data.
4. Document any interface assumptions.
5. Keep track of the routine's change history.
   
6. Comment on the routine's limitations.
7. Document the routine's global effects.
8. Document the source of algorithms that are used.
9. Use comments to mark program to make browsing easier

The author then provides guidelines to comment files, modules and programs:

1. Describe the purpose of each file
2. Include your name and phone number
3. Include a copyright statement