Comments

Java supports three kinds of comments: documentation, block, and single-line comments. These are described separately in the subsequent sections below. Here are some general guidelines for comment usage:

1. Comments should help a reader understand the purpose of the code. They should guide the reader through the flow of the program, focusing especially on areas which might be confusing or obscure.
2. Avoid comments that are obvious from the code, as in this famously bad comment example:

         i = i + 1;// Add one to i
   

3. Remember that misleading comments are worse than no comments at all.
4. Avoid putting any information into comments that is likely to become out-of-date.
5. Avoid enclosing comments in boxes drawn with asterisks or other fancy typography.
6. Commented code is good; Commented out code is bad. If there is any dead code that is history, do not comment the code out. Just remove them for the sake of readability. Version control systems already do a good job of storing previous revisions.
7. Temporary comments that are expected to be changed or removed later should be marked with the special tag "TODO:" so that they can easily be found afterwards. Ideally, all temporary comments should have been removed by the time a program is ready to be shipped. Example:

         // XXX: Change this to call sort() when the bugs in it are fixed
         list->mySort();