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?

6 Answers 6


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.

  • +1, that's a good call. I think my main grip with this is that I don't see it as two different target audiences, but you are right. Nov 30, 2011 at 12:10
  • 1
    @Andiaz - I find it useful to differentiate between outer edges of the system (like a service API) and classes inside it. I often work on projects where the convention is to javadoc all public methods, but I take a great deal more care on the outer classes to give some indication of how the class (and system) should be used. On the inner classes I assume the reader has more domain knowledge and minimize the javadoc, letting the method names speak more for themselves. Nov 30, 2011 at 12:32
  • 3
    @SteveJackson I agree, however, I've found myself using more Javadocs (even on private members) since IDEs (at least Eclipse and NetBeans) display the Javadoc comments in the code completion tooltips. Of course, they aren't as clean as the public facing interfaces, they provide tips/notes to other developers.
    – Thomas Owens
    Nov 30, 2011 at 12:43

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.

  • 2
    +1: It's not "either-or" in an exclusive sense. It's both in an inclusive sense.
    – S.Lott
    Nov 30, 2011 at 11:00
  • I definitely agree to this. Is there anything else you'd consider when it comes to javadocs in particular? Like, I can imagine that describing what a method does might be useful for e.g. APIs. Nov 30, 2011 at 12:09
  • Javadocs are very easily accessible from most IDE's. Make it easy to navigate on to further information.
    – user1249
    Nov 30, 2011 at 13:59
  • +1: The best comments I've seen have included references to the papers where the algorithms used were discussed in depth; that's not something that can be self-documented in variable/method names, and doesn't necessarily belong in doc-comments as the algorithm is part of the implementation and not the interface. Nov 30, 2011 at 20:36

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.

  • 3
    +1 my favorite is when the company code standard requires documented methods, but everyone uses a generator that just repeats what the code already says. Tedious, and useless.
    – Kryptic
    Nov 30, 2011 at 20:45

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.

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.


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)

Your Answer

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

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