Documentation

Kind of comments:
1. Repeat of the code. A repetitious comment restates that the code does in defferent words. It merely give the reader of the code more to read without providing additional information.
2. Explanation of the code. Typically used to explain complicated, tricky, or sensitive pieces of code. But 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.
3. Marker in the code. It isn't intended to be left in the code. It's a note to the developer that the work isn't done yet.
4. Summary of the code. It distills a few lines of code into one or two sentences.
5. Description of the code's intent. It explains the purpose of a section of code.

Commenting paragraphs of code
Most comments in a well-documented program are one-or two-sentence comments that describe paragraphs of code.
1. Write comments at the level of the code's intent.
2. Focus your documentation efforts on the code itself.
3. Focus paragraph comments on the why rather than the how.
4. Use comments to prepare the reader for what is to follow.
5. Make every comment count.
6. Document surprise.
7. Avoid abbreviations.
8. Differentiate between major and minor comments.
9. Comments anything that gets around an error or an undocumented feature in a language or an environment.
10. Justify vialations of good programming style.
11. Don't comment tricky code.

Commenting data declarations.
1. Comment the unit of numeric data.
2. Comment the range of allowable numeric values.
3. Comment coded meanings.
4. Comment limitations on input data
5. Document flags to the bit level.
6. Stamp comments related to a variable with the variable's name.
7. Document global data.

Commenting control structures.
1. Put a comment before each block of statement, if, case, or loop
2. Comment the end of each control structure.
3. Treat end-of-loop comments as a warning indicating complicated code.

Commenting routines.
1. Keep comments close to the code they describe.
2. Describe each routine in one or two sentences at the top of the routine.
3. Document parameters where they are declared.
4. Differentiate between input and output data.
5. Document interface assumptions.
6. Document 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 parts of your program.

Class documentation.
1. Describe the design approach to the class.
2. Describe limitations, usage assumptions, and so on.
3. Comment the class interface.
4. Don't document implementation details in the class interface.

File documentation.
1. Describe the purpose and content of each file.
2. Put your name, email addressm, and phone number in the block comment.
3. Include a copyright statement in the block comments.
4. Give the file a name related to its contents.