Usual form

An assert statement has two parts separated by a colon. The boolean condition must be true for execution to continue. If it is false, an AssertionError is thrown, which terminates execution and display the message string. Some examples:

assert jobQueue.size() == 0 : "process: queue should have been empty.";
								

assert connector != null : "merge: Connector null for " + rel;
								

When asserts are enabled, the assert statement checks the condition (queue empty, connector is not null, etc) which must be true for the program to function correctly. If it's true, execution continues. If connector is null (expression is false), an exception containing the message is thrown. This message is for the programmer, so it doesn't have to be user friendly.

Abbreviated form

The simplest form the assert statement specifies only a boolean expression that must be true. This is ok when there's not much to say, or the likelyhood of failing seems so remote it isn't worth the extra typing:

assert n > 0;
								

Do not use assertions for argument checking in public methods.

Argument checking is typically part of the published specifications (or contract) of a method, and these specifications must be obeyed whether assertions are enabled or disabled. Another problem with using assertions for argument checking is that erroneous arguments should result in an appropriate runtime exception (such as IllegalArgumentException, IndexOutOfBoundsException, or NullPointerException). An assertion failure will not throw an appropriate exception.

Do not use assertions to do any work that your application requires for correct operation.

Because assertions may be disabled, programs MUST NOT assume that the boolean expression contained in an assertion will be evaluated. Violating this rule has dire consequences. For example, suppose you wanted to remove all of the null elements from a list names, and knew that the list contained one or more nulls. It would be wrong to do this:

// Broken! - action is contained in assertion
assert names.remove(null);
								

The program would work fine when asserts were enabled, but would fail when they were disabled, as it would no longer remove the null elements from the list. The correct idiom is to perform the action before the assertion and then assert that the action succeeded:

// Fixed - action precedes assertion
boolean nullsRemoved = names.remove(null);
assert nullsRemoved;  // Runs whether or not asserts are enabled
								

Internal Invariants

Before assertions were available, many programmers used comments to indicate their assumptions concerning a program's behavior. You should now use an assertion whenever you would have written a comment that asserts an invariant:

if (i % 3 == 0) {
	...
} else {
	if (i % 3 == 1) {
		...
	} else {
		assert i % 3 == 2 : i;
		...
	}	
}								
								

Another good candidate for an assertion is a switch statement with no default case. The absence of a default case typically indicates that a programmer believes that one of the cases will always be executed. The assumption that a particular variable will have one of a small number of values is an invariant that should be checked with an assertion:

default:
	assert false : suit;
								

An acceptable alternative is:

default:
	throw new AssertionError(suit); 
								

Control-Flow Invariants

Place an assertion at any location you assume will not be reached. The assertions statement to use is:

assert false;								
								

Code now reads:

void foo() {
	for (...) {
		if (...) return;
	}
	assert false; // Execution should never reach this point!
}
								

Preconditions, Postconditions, and Class Invariants

While the assert construct is not a full-blown design-by-contract facility, it can help support an informal design-by-contract style of programming.

Do not use assertions to check the parameters of a public method. An assert is inappropriate because the method guarantees that it will always enforce the argument checks. It must check its arguments whether or not assertions are enabled. Further, the assert construct does not throw an exception of the specified type. It can throw only an AssertionError.

You can, however, use an assertion to test a nonpublic method's precondition that you believe will be true no matter what a client does with the class.

You can test postcondition with assertions in both public and nonpublic methods.

A class invariants is a type of internal invariant that applies to every instance of a class at all times, except when an instance is in transition from one consistent state to another. A class invariant can specify the relationships among multiple attributes, and should be true before and after any method completes. For example, suppose you implement a balanced tree data structure of some sort. A class invariant might be that the tree is balanced and properly ordered.

The assertion mechanism does not enforce any particular style for checking invariants. It is sometimes convenient, though, to combine the expressions that check required constraints into a single internal method that can be called by assertions. Continuing the balanced tree example, it might be appropriate to implement a private method that checked that the tree was indeed balanced as per the dictates of the data structure:

// Returns true if this tree is properly balanced
private boolean balanced() {
	...
}
								

assert balanced();