JavaDoc: The unloved child. A pragmatic approach.

Markus Eisele
5
Project documentation is an important but awkward thing to do. Same is true for JavaDoc. The few special comments in the Java source code that are delimited by /** ... */. This short post presents a very pragmatic approach to JavaDoc and outlines the general best practices for successful sourcecode documentation.

Why you should care!
Look at the NetBeans screenshot from the right. This is the tooltip you get, when trying to use the method. And now? What happens? Why? For what? How does this thing behave? Do you know what to do, if you see a getInstance() method?
The second screenshot gives you a more detailed idea about what you can achieve with writing some JavaDoc comments. And it applies to nearly any situation. If you are writing any kind of Java program you should keep in mind, that others probably want to use it's public API or need to use your implementation. This is not only true for framework developers but for anybody working within a team. Even if we are talking about component boundaries or utility classes. A class without documentation is trivial or worthless.

Hey: I am a programmer not a writer!
In theory, the general idea of commenting code sounds like a worthy one: Offer the reader detail, an explanation of what's going on. What could be more helpful than being helpful?
To make it short. I am not proposing to write too much beside the actual code. But that's exactly the problem. Beside the fact, that there are a couple of JavaDoc tags you could use it's also mostly up to you how much and what you write. The basic rule of thumb is:
Comments should say something code does not and cannot say.
(Source: 97 Things Every Programmer Should Know)
Does this help? Partly. This rule needs some interpretation. If you don't have source.jars at hand you probably don't have any code at all to look at. So: The less open the source is, the more extensive the comments should be. The second idea here is to look at your stakeholders. Who is the one intended to read the documentation? I don't like the idea to talk about skills here. My favorite is to classify the APIs into abstraction level. The higher the abstraction level, the more general and easier readable texts should be there. If you have a lower abstraction level, the texts could be more technical and probably less readable in terms of writing style. But, it's always good to remember the reworked old adage as a rule to keep in mind:
If it was hard to write, it should be EASY to read!

Ok: Tell me, which are the important parts?
Now you know, how and when to document your sources. What does this mean in practice?
If you refer to the Java SE 6 JavaDoc documentation you have 19 tags which you could use to. Here are the usage guidelines I propose for your next project:

1) Introduce a class header with a single line of documentation ("First Sentence") and an @author tag at a minimum.
2) Add as many documentation up the hierarchy as possible. Use {@inheritDoc} down the hierarchy.
3) Document all public methods except getters and setters with at last a single line and add @throws and @return. @params only if they are not obvious.
4) Use @link as internal reference and @see to add references to external resources.
5) Javadocs should get peer-reviewed, just like code.

Optional but possible needed:
- Introduce a meaningful file comments if needed (e.g. OSS or Company Copyright). Skip it, if not!
- If you are developing versions you should make broad use of the @deprecated tag where applicable.

That's all. Nothing more. Nothing less.
What are your best practices in projects? Let me know. Comments and other ideas are welcome!

Read more
JavaDoc Overview (Java SE 6)
How to Write Doc Comments for the Javadoc Tool
JavaDoc Tags
JLS Documentation Comments (first Edition)

Post a Comment

5Comments

  1. Very nicely done. I am such a pain in the posterior about making sure that the code has comments.

    I am particularly interested in making sure that the public API is documented. Otherwise, your fellow developers can not take advantage of what you are offering them.

    ReplyDelete
  2. Totally agree, with OP's recommendations. I think, if i am spending couple of hrs (avg) writing good class and it's unit tests, few mins to add java doc is really helpful. You can try to avoid, but in reality, either someone will be enhancing your code or you will be troubleshooting someone's code. Some complex code path, with few comments, makes life easier and less curse-y.
    Good recommendation for inherit java-doc. So if interfaces/abstract has javadoc to begin with, implementations doesn't need to add new one and tools add necessary tags automatically.

    ReplyDelete
  3. Just to add more, I love it, when posters put links to relevant external links. This makes his blog a good reference bookmarked link.

    ReplyDelete
  4. It's not just for others. You'll need your own Javadocs when you come to use your own libraries down the track. I hate seeing "Javadoc not found" when I'm working. It means somebody didn't do their job (too often it's me), and now it's costing me time to go sifting through the source code to work out whether the method or class does what I think it does...

    ReplyDelete
  5. I suggest adding a @see that links to example code, preferably a test class containing use-case tests (as opposed to non-explanatory unit tests).

    ReplyDelete
Post a Comment