Above is common to open source projects that do boldly follow those principles. Your left with entirely useless documentation. That doesn't explain anything about whats going on underneath, the possible effects, or even what the expected value is (could it be null or never null? I don't know, the Javadoc doesn't tell me).

So when should I document? Do I document everything even if it occasionally clutters code? Or do I document nothing since in my eyes its "obvious"?

8 Answers
8

In an ideal world, yes, you would document everything. However, on Earth, we have deadlines, feature cuts, families and friends to visit, vacations to take, only 24 hours in a day and only 365 days in a year. There's just not enough time to document everything. So, optimally, document everything you can (you won't get done), but get the most bang for your buck by:

Make code readable and method signatures as obvious as possible so that documenting is less likely to be needed.

Documenting the most obscure things first. Help out others by documenting the crazy hacks you had to do to get things out the door.

Firstly, document everything that DOES NOT make sense
–
ysolikOct 10 '10 at 17:47

1

Documenting everything does not mean a word document per method. It can be as small as a comment. Documenting everything in ways that don't make sense doesn't make sense, but attempting to clarify all obscure things for people that are more than minimally competent does.
–
Ryan HayesOct 10 '10 at 18:11

1

@ysolik I agree, but I think he meant 'Document everything that makes sense to document'
–
Alan PearceOct 10 '10 at 18:11

3

@Alan and @Ryan: the comment was not meant to contradict Ryan. It was just a play on words :) Btw, I agree with everything Ryan says, except "In an ideal world, yes, you would document everything." In an ideal world you won't have to document anything, the code would be self-documenting and self-explaining.
–
ysolikOct 10 '10 at 18:23

Basically it says that you shouldn't document something if it's not going to be useful (some documentation is just left to rot in a drawer) and document the least amount of information that is needed to understand a certain part of the project. Too much documentation just confuses the reader.

My suggestion on documentation is that if there is anything fancy in the code, that belongs in a document that should be kept up to date. Fancy being subject to much interpretation, in my mind is where something is done in a particular fashion that may have side effects that should be noted,e.g. something may be done to recursively to ensure that grandchild items are processed in going through a tree of nodes to perform some test on all the descendants. Articulating why something was done a particular way can be a good way to know whether or not there was a good reason to use something.

Personally I go with the approach of consider documenting everything. I.e. while coding I consider at every point whether documentation would add value. Most of the time the answer is yes for exactly the kinds of constraints and domain knowledge mentioned in the original question. E.g. null-ability, unique constraints, interpretation of the field in the wider domain.

To avoid duplication I tend to heavily document the main API classes with this kind of information. Then only document implementations and internals where there is non-obvious or inconsistent behavior. I find this works well as it's the users of the API which need the most help and documentation, it's generally safe to assume people modifying the implementation know the API so have this knowledge.

I also tend to document just the getters. I don't duplicate documentation onto setters, field definitions and constructor parameters. I only document non-obvious behavior such as defaults in these places. Any behavior that can be inferred from the getter documentation isn't documented. For example, if the getter is documented as never-returning null, I generally don't document that you can't pass null to the setter, unless there is a default.

Some people like to mark this act of "considering documentation" by adding empty comments where they have considered documentation but found it unnecessary. I don't like this practice as it just clutters up the code and gets in the way.