Take the 2-minute tour ×
Programmers Stack Exchange is a question and answer site for professional programmers interested in conceptual questions about software development. It's 100% free, no registration required.

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

share|improve this question
    
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 '12 at 9:16
add comment

8 Answers 8

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.
share|improve this answer
20  
Firstly, document everything that DOES NOT make sense –  ysolik Oct 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 Hayes Oct 10 '10 at 18:11
1  
@ysolik I agree, but I think he meant 'Document everything that makes sense to document' –  Alan Pearce Oct 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. –  ysolik Oct 10 '10 at 18:23
1  
@ysolik Oh man, that would be the ultimate ideal world. –  Ryan Hayes Oct 10 '10 at 18:44
show 2 more comments

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

share|improve this answer
add comment

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.

share|improve this answer
add comment

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.

share|improve this answer
add comment

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

share|improve this answer
add comment

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.

share|improve this answer
add comment

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.

share|improve this answer
add comment

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.

share|improve this answer
add comment

Your Answer

 
discard

By posting your answer, you agree to the privacy policy and terms of service.

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