Self-documenting code vs Javadocs?

Question

Recently I've been working on refactoring parts of the code base I'm currently dealing with - not only to understand it better myself, but also to make it easier for others who are working on the code.

I tend to lean on the side of thinking that self-documenting code is nice. I just think it's cleaner and if the code speaks for itself, well... That's great.

On the other hand we have documentation such as javadocs. I like this as well, but there's a certain risk that comments here gets outdated (as well as comments in general of course). However, if they are up-to-date they can be extremely useful of say, understanding a complex algorithm.

What are the best practices for this? Where do you draw the line between self-documenting code and javadocs?

Answer 1

Self-documenting code (and in-code comments) and Javadoc comments have two very different target audiences.

The code and comments that remain in the code file are for developers. You want to address their concerns here - make it easy to understand what the code does and why it is the way it is. The use of appropriate variable names, methods, classes, and so on (self-documenting code) coupled with comments achieves this.

Javadoc comments are typically for users of the API. These are also developers, but they don't care about the system's internal structure, just the classes, methods, inputs, and outputs of the system. The code is contained within a black box. These comments should be used to explain how to do certain tasks, what the expected results of operations are, when exceptions are thrown, and what input values mean. Given a Javadoc-generated set of documentation, I should fully understand how to use your interfaces without ever looking at a line of your code.

Answer 2

Code says how. Comments say why, and perhaps even why not.

It is your job to provide both to future readers and maintainers of your code. Put all you can in the code, and the rest in the comments.

Note that the things hardest to capture are the design decisions - remember those too.

Answer 3

Using Javadocs does not make a real difference - since the generated docs contain the name of your functions together with the text from the comments, there is absolutely no reason why you should repeat anything in the comments that is clear from the function name itself.

If, on the other hand, you have a function where one has to look at the implementation first to understand what it is good for (thus not making this information available to Javadocs) , then the code is IMHO not self-documenting, no matter how clear the implementation is.

Answer 4

I think that with javadocs, things are the same as with any documentation at all - main rule is:

follow the audience

Do many people read your javadocs? If yes, it makes good sense to invest efforts into getting it right.

Do your readers tend to skip reading code in favor of studying javadocs? If yes, it makes twice as much sense to spend efforts on writing it well.

• This is exactly the case with JDK documentation. Guess Sun/Oracle spent a lot efforts on these and they seem to have a nice payback in API docs being used a lot by community.

Now, is it your case? If not, think twice whether efforts invested into javadocs are justified.

As already pointed above, listen to the audience to find out the way.

• If you hear active complaints about insufficient documentation, consider investing into improving it.
   
  If, on the other hand, all you hear is developers whining about braindead rules forcing them to waste time on useless typing, well, then chances are high that your javadocs efforts are like investing into subprime mortgages. Think of better investments instead.

Answer 5

I just want to comment on the concern that Javadoc comments might get outdated. While @JonathanMerlet is right in saying that the Javadoc should be stable, you can also help by reviewing Javadoc and comments as well as code during peer review. Do the comments match with what the code is doing? If not, which is incorrect, and insist the developer fix it. Try to encourage other developers to do the same. This helps keep not only external documentation (Javadoc comments) up-to-date, but also any regular code comments as well. This helps developers who come along after your refactoring understand the code more quickly and easily, and makes maintaining it much simpler in the future.

Answer 6

I think that javadocs is appropriate for the parts that should stay stable (API) so that the risk of the comments going out of date is minimized, whereas self documenting code is great for what is subject to frequent change (implementation). Of course, APIs may change during the course of the project, but having the header just before the declaration, keeping both in sync is not that hard (compared to a comments on multiple lines explaining several lines of code)