On 19 Oct 2010, at 12:43 , Angelo van der Sijpt wrote: > Our current coding guideline [1] does not contain guidelines for the way we > should use Javadoc. After a short discussion, Ivo and I decided that we > should _not_ use tags like @inheritDoc or @see if their _only_ goal is to > point to the interface method we implement or the base method we override; > both your IDE and the Javadoc tool can handle these links fine.
Agreed. Just like all modern IDE's are able to pick up javadoc straight from the source, this is unnecessary. > A thing we don't quite agree on is using Javadoc that 'doesn't say anything', > e.g. "gets the name" on a getName() method. If this is in a public API > interface, the javadoc should be improved, but as long as we have not > improved it yet, we could remove it, so we don't create the impression that > this is the final doc. The "gets the name" example is indeed useless, so you might as well remove such statements. They do not add anything. A way to improve on them is to actually explain what the thing is you're getting. If that does not make sense either, I'm in favor of removing the comment altogether (even on public interfaces). Greetings, Marcel
