Question

On my previous job, providing all methods with javadoc was mandatory, which resulted in things like:

/**
 * Sets the Frobber.
 *
 * @param frobber The frobber
 */
public setFrobber(Frobber frobber) { ... }

As you can see, the documentation takes up space and work, but adds little to the code.

Should documenting all methods be mandatory or optional? Is there a rule for which methods to document? What are pros and cons of requiring every method to be documented?

Answer 1

“providing all methods with javadoc was mandatory”

I strongly suspect that documenting all methods was mandatory, but providing javadoc comments was all that could be automatically enforced and hence all that was uniformly done.

Personally I think it’s better to have no javadoc than completely useless javadoc – at least you can see from a glance at the HTML which methods are undocumented, because there are no descriptions of the parameters etc.

Documentation is frequently underrated, because it always seems less important and urgent when you’re writing the code, than it does when you’re using it later. But the style and form of documentation is often overrated – auto-generated XML nonsense is still nonsense. Given the choice, I’d rather have the code comment // Sets this object to use the specified frobber for all future frobbing, than your zero-information javadoc.

For all I know from your docs, the function doesn’t actually modify this object at all, it might call the set() function on frobber, or it might be while(!frobber.isset()) { refrigerator.add(frobber); sleep(3600); refrigerator.remove(frobber); } Hence it “sets the frobber”. I’m sure I read somewhere that “set” is the word with the most distinct definitions in the OED. Brief descriptions are ambiguous and hence misleading, and the purpose of documentation is to stop people relying on your source, and hence on details of your current implementation. My comment doesn’t really take any longer to write than it took to add “Sets the frobber” and “the frobber” to the IDE-generated javadoc stub. It doesn’t explain what frobbing is or when this object does it (hopefully that’s elsewhere in the class docs) but at least it tries to tell you what the function does.

As for when to mandate documentation – I think every interface must be documented. If you’re not defining Java interface s, the “interface” is every public and protected method, and every package-protected method unless the package is tiny. Implementation doesn’t have to be documented, although it should be commented if the way it works is non-obvious. Documentation might be as simple as the sentence in my comment above – you don’t necessarily need a separate sentence for each parameter if the method description already says what they are.

If you have code review, then IMO the answer is to review comments and documentation at the same time. If you don’t have code review, then you need a cone of shame for whichever developer most recently forced someone else to come over and ask what the code actually does.

The same applies to anyone who relied on undocumented behaviour of a function, with a result that an implementation change that didn’t change the interface, breaks their code. The way you enforce that code be documented, is to complain that you can’t call it until you know what it guarantees to do. Arbitrary rules like, “javadoc comments must exist” become less important, at least for functions that other developers need to call.