Should you document everything or just most?

Question

It seems a bit of a controversial subject to document everything, including the "JavaBean" syntax of getters and setters for fields: People say its needlessly long and repetitive breaking DRY (don't repeat yourself), that the naming convention should explain everything, and it clutters code/documentation. Sometimes those arguments work. But other times, you end up with this:

Above is common to open source projects that do boldly follow those principles. You're left with entirely useless documentation. That doesn't explain anything about what's 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 it's "obvious"?

Answer 1

Document everything that makes sense to document.

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.
• Document the why before the what - Don't comment what something does, like "Iterate over the customer records where balance is less than zero and rating is less than one and add them to the exemptCustomers list". Document why you are adding them to the list in plain english (or your team's language), like "Since these customers have a negative balance and low ratings, they are causing us to lose money, so exclude them from being able to check out.

Answer 2

Keep documenting until you can watch someone else read it without feeling the need to explain anything.

Answer 3

This past week there was a great article regarding documentation over at The Daily WTF. I think it says everything, so I'll just leave the link:

http://thedailywtf.com/Articles/Documentation-Done-Right.aspx

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.

Answer 4

Really depends on how readable the code is to the audience reading it. Figure out who the audience is for reading your code, and have someone that meets that profile read your code.

Another approach would be to review your own code after a week and see if you still understand what you did, if you don't, document it and review the code in two weeks or so.

Answer 5

While I appreciate a clear and extensive documentation, there's nothing like self-documenting code. So, the bottom line (for me) is:

Be very suspicious of (source code) documentation; try and make it redundant by improving the code, but don't shy away from documenting clearly and completely when necessary.

Of course, under certain circumstances, documentation may be required for reasons other than 'explaining what the code is doing' (eg: large team base, organization standards, and so on so forth).

Answer 6

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.

Answer 7

In simple terms, documentation is there to help the developers now, and the maintainers in the future.

If you remember that simple maxim, then the level of documentation should be self-defining.

Documentation, for the sake of documentation, is a waste of time... but explaining today what you are doing is more helpful than someone having to reverse-engineer your code in five years time.

Answer 8

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.