1. [Mandatory] Javadoc should be used for classes, class variables and methods. The format should be ‘/** comment **/‘, rather than ‘// xxx’.

Note: In IDE, Javadoc can be seen directly when hovering, which is a good way to improve efficiency.

2. [Mandatory] Abstract methods (including methods in interface) should be commented by Javadoc. Javadoc should include method instruction, description of parameters, return values and possible exceptions.

3. [Mandatory] Every class should include information of author(s) and date.

4. [Mandatory] Single line comments in a method should be put above the code to be commented, by using // and multiple lines by using /* */. Alignment for comments should be noticed carefully.

5. [Mandatory] All enumeration type fields should be commented as Javadoc style.

6. [Recommended] Local language can be used in comments if English cannot describe the problem properly. Keywords and proper nouns should be kept in English.

Counter example: To explain “TCP connection overtime” as “Transmission Control Protocol connection overtime” only makes it more difficult to understand.

7. [Recommended] When code logic changes, comments need to be updated at the same time, especially for the changes of parameters, return value, exception and core logic.

8. [For Reference] Notes need to be added when commenting out code.

Note: If the code is likely to be recovered later, a reasonable explanation needs to be added. If not, please delete directly because code history will be recorded by svn or git.

9. [For Reference] Requirements for comments:
  1) Be able to represent design ideas and code logic accurately.
  2) Be able to represent business logic and help other programmers understand quickly. A large section of code without any comment is a disaster for readers. Comments are written for both oneself and other people. Design ideas can be quickly recalled even after a long time. Work can be quickly taken over by other people when needed.

10. [For Reference] Proper naming and clear code structure are self-explanatory. Too many comments need to be avoided because it may cause too much work on updating if code logic changes.

Counter example: 

  1. // put elephant into fridge
  2. put(elephant, fridge);

The name of method and parameters already represent what does the method do, so there is no need to add extra comments.

11. [For Reference] Tags in comments (e.g. TODO, FIXME) need to contain author and time. Tags need to be handled and cleared in time by scanning frequently. Sometimes online breakdown is caused by these unhandled tags.
  1) TODO: TODO means the logic needs to be done, but not finished yet. Actually, TODO is a member of Javadoc, although it is not realized in Javadoc yet, but has already been widely used. TODO can only be used in class, interface and methods, since it is a Javadoc tag.
  2) FIXME: FIXME is used to represent that the code logic is not correct or does not work, should be fixed in time.