How To Comment With JavaDoc

Put

  1. the WHAT in the name
  2. the HOW in the code, and
  3. the WHY in the comment

Sometimes there is no WHY. The reason and intentions are more than obvious (getters / setters, toString, equals methods etc.). Writing JavaDoc for the obvious cases should be considered as defect...

Thanks Kai Windmöller for the suggestion / comment!

See you at Java EE Workshops at MUC Airport, particularly at: Effective Java EE 7!

Comments:

Hi Adam,

Thanks for your frequent and interesting posts... let me comment this one, as I don't fully agree with it.

I do agree with the fact that obvious cases (the ones you gave : getters, setters, overrridings, etc.) may not contain javadoc, which is not useful in THAT cases.

But as a developer, you should always keep in mind that your classes and methods could be useful for others, and this is the main purpose of the javadoc : to be able to generate a html-summary of packages and classes, for future users... which may not have the whole sources. In that case, javadocs are far more necessary than simple in-code comments.

Then the HOW, and maybe complements of the WHAT and some USAGE précisions are necessary in these cases.

Otherwise, your classes may not be reusable, thus preventing code factorization and maintenance fragmentation.

IMHO, you have to keep this in mind too, and always try to imagine the future user's questions.
David.

Posted by David on November 14, 2013 at 03:35 PM CET #

@David:
I don't care how the library I'm using solved the problem. I just want my job done. Leave the HOW in the code - that's where it belongs.

@Adam:
Great advice, as usual!
Chosing the name wisely frequently answers the WHY as well as the WHAT. Just think of System.out.printTextAndStartANewLine(). Only lazy programmers shortening the name to - say - System.out.println() have to explain the WHAT. The WHY doesn't have to be explained in any case.

Posted by Stephan on November 16, 2013 at 12:40 AM CET #

@Stephan: System.out.println has historical significance from stdout that are familiar to the vast majority of programmers. Having to think of method names which convey in detail what the method actually does is not something I encourage programmers to do, their creativity is best used in the logic in the method itself. Any method that is so complicated that it defies concise naming practices is a hint that the design and/or implementation is not what it should be.

Documenting code at the method level is something that is important when exposing an API for 3rd parties. Documentation for internal purposes as a procedural "must-have" doesn't work in practice and because it is the last thing that gets updated over the lifetime of the code base it is a source of confusion and soaks up valuable developer resources making sure that the internal documentation matches the actual implementation.
The only place I consider JavaDocs as necessity for internal consumption is for tests. It focusses the developers mind by getting them to describe the tests they are actually implementing and allows others to see what really should be happening in the test itself.
I always encourage developers in teams to put this into practice and get into the habit of writing the test documentation before implementing a test or changing an existing one. Part of the code review process I use involves reviewing the test documentation before anything else. This ensures consistency in the code too.

Posted by Andy on November 21, 2013 at 07:57 PM CET #

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