On Tue, Oct 19, 2010 at 1:48 PM, Angelo van der Sijpt <angelo.vandersijpt at luminis.eu> wrote: > > 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.
Valid point too. I guess it one of those religious discussions we tend to get ourselves into when it comes to conventions... +0 ;) regards, Bram
