Code Complete Documentation

[nilaccount]

Need

Understand one point that can be automated when producing documentation

Notes

• Good comments don’t repeat the code or explain it. They clarify its intent. Comments should explain, at a higher level of abstraction than the code, what you’re trying to do.
• When I read comments, I want it to be like reading headings in a book, or a table of contents. Comments help me find the right section, and then I start reading the code. It’s a lot faster to read one sentence in English than it is to parse 20 lines of code in a programming language.
• “If someone claims they don’t need to write comments and are bombarded by questions in a review—several peers start saying, ‘What the heck are you trying to do in this piece of code?’—then they’ll start putting in comments. If they don’t do it on their own, at least their manager will have the ammo to make them do it.
• Routine One has an incorrect comment. Routine Two’s commenting merely repeats the code and is therefore useless. Only Routine Three’s commenting earns its rent. Poor comments are worse than no comments.
• Kinds of Comments
  • Repeat of the Code: A repetitious comment restates what the code does in different words. It merely gives the reader of the code more to read without providing additional information.
  • Explanation of the Code: Explanatory comments are typically used to explain complicated, tricky, or sensitive pieces of code. In such situations they are useful, but usually that’s only because the code is confusing. If the code is so complicated that it needs to be explained, it’s nearly always better to improve the code than it is to add comments. Make the code itself clearer, and then use summary or intent comments.
  • Marker in the Code: A marker comment is one that isn’t intended to be left in the code. It’s a note to the developer that the work isn’t done yet.
  • Summary of the Code: A comment that summarizes code does just that: It distills a few lines of code into one or two sentences. Such comments are more valuable than comments that merely repeat the code because a reader can scan them more quickly than the code. Summary comments are particularly useful when someone other than the code’s original author tries to modify the code.
  • Intent and summary comments are the most useful ones
• Use styles that don’t break down or discourage modification. Any style that’s too fancy is annoying to maintain.
• Integrate commenting into your development style. The alternative to integrating commenting into your development style is leaving commenting until the end of the project, and that has too many disadvantages.
• Optimum number of comments, there's a balance. Rather than focusing on the number of comments, focus on whether each comment is efficient. If the comments describe why the code was written and meet the other criteria established in this chapter, you’ll have enough comments.
• Comments should explain why the code works now, not why the code didn’t work at some point in the past.

for i = 1 to maxElmts – 1 -- fixed error #A423 10/1/92 (scm)