Identify your target audience

Usually these are developers that use or evaluate the use of your software. Use a language that is understood by your audience. For Example don't use "difficult" english words if you know that you have a lot of non native speakers in your team.

Define the intention of your documentation

Usually developers write documentation that documents the functionality their Methods, Classes or Interfaces expose. Don't try to write a programmers guide or mix API documentation and programmers guide.

/**
 * Calculates a true random number based on the random seed.
 * The seed is initialized by the init() method.
 */
public int calculateRandom() {
	//...
}

instead of

/**
 * Call this method after calling init() - generates seed - to generate true random numbers.
 */
public int calculateRandom() {
	//...
}

Ignition Sentence

Start comments with ONE short, crisp and informative sentence - we call it ignition sentence!

Implementation independent comments

Describe the functionality the class/method/interface exposes. Don't create a step by step description how the algorithm works. A good comment tells the reader how to use this class/method/interface in his code!

Tip: Try to cover the implementation of your class/method/interface with a sheet of paper and write down your ignition sentence.

Method descriptions begin with a verb

This rule is tightly coupled with "Active instead of Passive"! Example:

/**
 * Returns the maximum value of operands a and b.
 */
public int max(int a, int b) {
	//...
}

instead of

/**
 * The maximum value of operands a and b is returned.
 */
public int max(int a, int b) {
	//...
}

Active instead of Passive

Use calculates the mean of value a and b instead of The mean of value a and b is calculated, Creates a new instance of Helper Class instead of A new instanceo of Helper Class is returned.

This rule is tightly coupled with "Method descriptions begin with a verb".

Use third person not second person!

Use the same language as if you would describe the method/class/interface to a peer that sits next to you. Example:

Creates a new instance of Helper Class instead of Create a new instance of Helper Class.

Avoid redundancy

Don't use constructs like This method, This class, This interface to start the ignition sentence. The subject of your comment is already defined by the position of the comment.

Be specific!

Use the or this instead of a or an. Don't use any words that express uncertainty like may, should or would!

It's ok to use phrases!

If you feel that your thoughts are best expressed by a short phrase - do so. This is especially true if you comment method parameters or return values.

Add extra value

Write comments that add extra value to your source code! Example:

/**
 * Calculates a true random number based on the random seed.
 * The seed is initialized by the init() method.
 */
public int getRandom() {
	//...
}

instead of

/**
 * Gets a Random int.
 */
public int getRandom() {
	//...
}

Distinguish between overloaded methods

Use your comments to distinguish between overloaded methods. Emphasize differences! Example:

/**
 * Adds an item at the end.
 */
public void add(object item) {
	//...
}
		 
/**
 * Adds an item at the given position.
 * Items after position are pushed back.
 */
public void add(object item, int position) {
	//...
}

This instead of The

Use "this" instead of "the" when referring to an object created from the current class. Example:

/**
 * Returns the iterator for this collection.
 */
public Iterator iterator() {
 	//...
}

Simple Language

Use a clear and common language. Avoid abbreviations. Use also known as instead of aka, that is or to be specific instead of i.e., use for example instead of e.g.(To be continued...)

Reflect on your Comments

Use your documentation as a starting point for refactoring your code design.

Tip: Every time you want to use an AND in your ignition sentence this is a good indicator that you violated The Single Responsibility Principle.

Tip: If the starting verb in your comment is not part of the method name consider renaming that method. Example:

/**
 * Calculates a true random number based on the random seed.
 * The seed is initialized by the init() method.
 */
public int getRandom() {
	//...
}