22

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:

alt text

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"?

2
  • 4
    to a certain degree this shows a naming problem e.g. getDate should be getCreationDate or getExpiryDate or what ever make sense in the domain. Of course naming isn't a panacea.
    – jk.
    Sep 20, 2012 at 9:16
  • Note: this came up in the CV review queue. I think it should be kept open - the question is on-topic (documentation is SDLC) and the answers are really good and answer the question in a reasonable amount of space (i.e. not too broad)
    – user22815
    Feb 11, 2017 at 23:58

8 Answers 8

25

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.
7
  • 27
    Firstly, document everything that DOES NOT make sense
    – ysolik
    Oct 10, 2010 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 Hayes
    Oct 10, 2010 at 18:11
  • 1
    @ysolik I agree, but I think he meant 'Document everything that makes sense to document' Oct 10, 2010 at 18:11
  • 4
    @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.
    – ysolik
    Oct 10, 2010 at 18:23
  • 1
    @ysolik Oh man, that would be the ultimate ideal world.
    – Ryan Hayes
    Oct 10, 2010 at 18:44
7

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

5

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.

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.

4

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).

1
2

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.

1

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.

0

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.

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge that you have read and understand our privacy policy and code of conduct.

Not the answer you're looking for? Browse other questions tagged or ask your own question.