Lon Hosford Java Course Materials

These Comments are Classified

You might consider classifiying comments on how they serve different parts of your source file. Here is a mental list that I follow.

1. Source file comment: Usually at the top of the source file documenting the file and its contents and history.

2. Programming unit comment: This is a comment explaining a programming unit. In Java we have methods and classes as a programming unit. In other languages with have the equivalent sometimes called functions and procedures. Generally I will not comment the main function if that is the only function. The source file comment is enough.

3. Major programming unit processing steps: These are comments that detail the beginning and even the end a group of steps related to working on meaningful processing step in the programming unit.

4. Programming block comments: We may have not seen all of these yet but they include if, else, switch, for, while, do, catch, try, and finally blocks. Comments before each block.

5. Expressions comments: These are comments that explain the expression (formula) that create data.

6. Data comments: Very critical comments that document each variable or constant value. No matter how clear your variable name is to you, assume it is not clear to anyone else.

7. Preprocessor comments: I will occassionally comment the preprocessor lines. These are the import statement in Java.