Comments

Write the least possible comments

• Prefer coding to commenting

• The code should document itself as most as possible

• Many and long comments are code smell

Comments Should Be

• Meaningful

• Necessary

• Readable

Bad Comments

• „Commented out” code - Remove it, find it in the version control system

• Separators, markers

• Redundant

• Misleading

• Out-of-date

• Obvious

• Unnecessary

• Funny

• Closing brace comment

• Attributes - author, date, issue number, etc.

• Non-English

• Too many HTML markers

• Historical

• Prone to copy-paste error

Good Comments

• TODO comments

• Warnings - e.g. "Not threadsafe"

• Limitations - e.g. "It works only with a sorted list"

• Javadoc comment to public API - for high level service methods

• Comment empty blocks

• Less is more.

Example: Bad: Comments

// Redundant, obvious:
/**
* gets the value of Name
*/
public String getName();

// Funny, unnecessary:
// I invented this part, but do not know why

Example: Good: Javadoc comment

/**
* Returns an Image object that can then be painted on the screen.
* The url argument must specify an absolute {@link URL}. The name
* argument is a specifier that is relative to the url argument.
* <p>
* This method always returns immediately, whether or not the
* image exists. When this applet attempts to draw the image on
* the screen, the data will be loaded. The graphics primitives
* that draw the image will incrementally paint on the screen.
*
* @param url an absolute URL giving the base location of the image
* @param name the location of the image, relative to the url argument
* @return the image at the specified URL
* @see Image
*
* @deprecated Use {@link getImage(Long id)} instead.
*/
@Deprecated
public Image getImage(URL url, String name) {
    try {
        return getImage(new URL(url, name));
    } catch (MalformedURLException e) {
        return null;
    }
}