Adam Bien's Weblog

Tuesday Oct 30, 2007

How to JavaDoc (efficient and maintainable) - 6 steps

Most of the JavaDoc comments are worthless. They describe redundantly already existing information and obvious facts. Many developers are indirectly forced (by e.g. QA) to write dumb Javadoc, only to increase some metrics. However this approach is really expensive, because:

  1. Someone has to write the JavaDoc
  2. ...and even worse - in the mainainance phase all developers are forced to filter out relevant things and ignore worthless information

The classic sample is:

/**

* This is a setter which sets the name

@param name - the name to be set

*/

public void setName(String name) {...

The already existing information from the method's signature is replicated to the javadoc. In my opinion such a javadoc is superfluos, every java developer knows what getters and setters are. The same anti-pattern is often applied to document other elements - not only obvious Java Bean "components".

Instead of writing superfluos documentation, you could also introduce a new Javadoc tag or annotation to mark such use cases e.g. @Obvious. In this particular case the QAs should be happy with the doc coverage and developers could silently ignore the doc.

Really good javadoc should be written accoding to the following rules:

  1. Document the background knowledge, the intention and not the result
  2. Try to capture the concepts in a central place (e.g. wiki) - and only reference to the contents
  3. Document obvious facts with marker tags - don't describe them over and over again (be DRY) [see Marker Annotation in p4j5]
  4. Include in your documentation samples, how-to  etc. (source code rules)
  5. Don't allow default javadoc comments generated by the IDE
  6. Sometime "No Doc, is the Best Doc" - try to minimize the amount of documentation and describe only the key concepts.
Actually the same ideas for good OO systems can be applied for good documentation as well.


NEW: Java EE 7 Testing and Quality Workshop

A book about rethinking Java EE Patterns

Comments:

When coding Java Beans and Entity beans, my big pet peeve is that I document (and annotate) the private fields, and there is no way to just absorb that documentation for the getters/setters. Since private access is typically not documentated by JavaDoc, this forces users to provide docs for getters and setters. And I hate that I need to document the same thing 3 times. Javadoc needs a strategy to deal with this problem.

Posted by Anthony Whitford on October 31, 2007 at 10:11 PM CET #

You mean 'intention', not 'intension'.

Posted by Anonymous on November 01, 2007 at 01:11 AM CET #

Your system time is wrong.

Posted by Anonymous on November 01, 2007 at 01:13 AM CET #

The @Obvious annotation is not a bad idea at all! :D

Posted by Paris Apostolopoulos on November 01, 2007 at 11:39 AM CET #

Anonymous,

1. I corrected intension -> intention. Thank you very much.
2. I hope no my, but my server's system time is wrong. I will check it - thanks.

Posted by Adam Bien on November 01, 2007 at 12:43 PM CET #

Paris,

thank you for the nice comment - request a beer at the next J1's after dark :-),

cheers,

adam

Posted by Adam Bien on November 01, 2007 at 12:44 PM CET #

Anthony,

you are right. But why not document the private fields only? Getters and setters are just redundant. I go in most cases further and use my own annotations to provide additional meta data.

In most cases I try to built more fluent domain objects and get rid of getters/setters...

thanks you for the comment

Posted by Adam Bien on November 01, 2007 at 12:47 PM CET #

>mainainance

is a misspelt word

Posted by anon on November 02, 2007 at 07:44 PM CET #

Nice tips. every programmer would love this tips.

@obvious annotation is cool.

Posted by ketan on November 02, 2012 at 04:49 PM CET #

Before worrying about too much documentation, I would be more concerned with people not writing enough documentation. Too much documentation is a good problem to have. However, your example makes sense. I would like to amend your first rule. It seems to me the result should be explained for cases where a method changes a value that the user should be aware of. For example, when a method call leaves an object in a changed state that isn't apparent by the intention of the method. It's good for the documentation to make notes of such things.

Posted by David on January 03, 2013 at 11:40 PM CET #

To much documentation IS NO DOCUMENTATION.

If most of it is obvious crap that just repeats the information you can clearly see from the method/attribute/class name then no one notices the important parts.

Posted by Adam Walczak on September 10, 2013 at 05:39 AM CEST #

The two key factors that explain WHY you use javadoc comments are:

1. To generate effective API documentation.
2. To make the source code more readable.

Both of these factors assume that you know some facts about what makes comments effective and readable (i.e. useful). For example:

1. The intended reader isn't you.
2. The intended reader doesn't have your domain knowledge or your coding skills. (Which means that whatever is obvious to you isn't necessarily obvious to the reader!)
3. Effective commenting/documentation makes the code more maintainable.
4. The code you write represents an investment in intellectual property that is wasted if you are the only one who can understand it and do anything with it. Obfuscating your code is dishonest and unethical.
5. The javadoc compiler doesn't understand your code, so it can't create comments on its own. You have to stick to the required comment syntax and taxonomy to allow the javadoc compiler to do its job.

Remember that "redundancy" is a matter of perspective. What you see and understand when you read code is unknowable to the javadoc compiler -- just like the java compiler will not understand your code if you don't use correct java syntax.

Posted by Dan Azlin on November 08, 2013 at 11:54 PM CET #

Post a Comment:
  • HTML Syntax: NOT allowed
realworldpatterns.com
...the last 150 posts
...the last 10 comments
Links
License