10

I want to write Javadoc in DRY way. But the oracle document about Javadoc says write same thing again in overload method comment. Can't I avoid repetition?

Sanghyun Lee
  • 829
  • 1
  • 7
  • 20

2 Answers2

3

I sprinkle {@inheritDoc} directives here and there in my Javadoc comments when overriding methods from superclasses or implementing interface-defined methods.

This works well for me at least, avoids repetition in the source code, and you can still add specific information to the particular Javadoc comment if there is a need to do so. I don't consider the fact that the Javadoc comment itself is fairly bare to be any issue when all it takes in a decent IDE is to hover over the associated identifier name to get the rendered Javadoc with references and all.

user
  • 2,703
  • 18
  • 25
2

The point of documentation is to illuminate future users of an item. This is partly for the convenience of the author, so that he or she does not have to be contacted whenever someone cannot figure out how the thing works. Mostly, however, it is for the benefit of the people who need to use or support the thing.

As such, the point should be clarity, as opposed to convenience for the author. You cannot expect folks to hunt up and down through your API documentation because you were essentially too lazy to repeat yourself. Suck it up--Javadoc will be repetitive.

That said, there's no reason, if you're clever, you can't write a program that would stick comments into your code based on markers or some other criteria. It may be more trouble than it's worth. Or not.

Matthew Flynn
  • 13,345
  • 2
  • 38
  • 57
  • 5
    No, don't repeat yourself; it's just that much more overhead to keep everything in synch. If there's new information about the overloaded implementation, then write only that. I think it IS reasonable to expect users of a type to look at the javadocs of its supertypes, and tools like Eclipse make it very easy for them to do so. – Dawood ibn Kareem Jan 13 '12 at 03:26