Home Commenting preconditions and postconditions

Preconditions and Postconditions

When writing a method header comment, focus on describing the preconditions and postconditions for that method. You are required to do this for both public and private methods.

Implementation detail

Your method header comments should never include implementation detail – information about how exactly the method or class works.

One useful way of determining if something would count as implementation detail is to ask yourself if your code would survive a total internal rewrite. If it doesn't, odds are it contains implementation detail.

Assumptions about the client

Your comments should never make any assumptions about the behavior of the client.

Retain only useful information

We do not enforce any sort of length requirement or restriction for comments. You are free to make your comments as long or short as you'd like, so long as don't omit any important information and all the information included is actually useful.

Formatting precondition/postcondition comments

We are not picky about how exactly you document your preconditions and postconditions as long as the information we're looking for is there. You could either use the style we've used in this style guide, use Javadocs format, or use your own conventions.

See formatting your comments for more details.