On Oct 19, 2010, at 1:36 PM, Bram de Kruijff wrote: > On Tue, Oct 19, 2010 at 12:55 PM, Marcel Offermans > <marcel.offermans at luminis.nl> wrote: >> 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). > > I like consistency by keeping javadoc on all public methods. First > point is it "gets the name" but can it be null or throw an exception? > Second point is that I'm not sure you have a javadoc required unless > its useless rule in checkstyle :)
I agree that when we have something useful to say there, we should, e.g. "gets the name in the current locale, but will return 'wazaap' if no locale is set". However, as long as we have not taken the time to write anything informative, I'm in favor of removing them altogether. Angelo
