General guidelines

Claim your code

  • Each Java class should have a @author tag in the class comments. When making (significant) changes, you should also add yourself in the list of authors. Always use your full name.

Javadocs and codes comments

  • Each Java class should have comments that clearly describe the purpose of the class. For interfaces specifically, each and every method must have clear comments.
  • Public methods should be commented if the meaning is not entirely clear from the method and parameters names (is it ever?). When the method overrides or implements a method, then repeating the javadoc is not needed.
  • Comments in the code are recommended when they explain a block of code or when they explain why things are done in a certain way. Repeating the code in human readable wording is wasteful.

General conventions

  • Use "@todo" comments to indicate shortcuts or hacks which should be fixed. Better still is just to do it right and not have the shortcut.
  • Import statements should never use wildcards. Always use the correct list of classes to import.