Hi Alexander,

Alexander Kiel wrote:
> Hi Max,
> 
> First, I will respect every code style of FOP. Its just a matter of
> discussion.
> 
>>> Really? That means commenting every public method even simple Getters
>>> and Setters?
>> Yes. Simple Getter and Setters are the only place where you can
>> publicly document private variables. (in most cases, comment in the
>> getter and link from the setter)
> 
> Yes thats right. But is this Javadoc better than no Javadoc?
> 
> public class Person {
> 
>     /**
>      * Returns the first name of this person.
>      *
>      * @returns the first name of this person.
>      */
>     public String getFirstName() {
>         return firstName;
>     }
> }

Except in the simplest cases like that one, there is always a bit of
additional information that can be added about the variable or its
usage.


>>> Commenting equals(), hashCode() and toString()? I think,
>>> this would be only clutter.
>> /** {...@inheritdoc} */
> 
> In my eyes this is enough clutter. I saw classes in FOP with maybe 10
> methods using this /** {...@inheritdoc} */. It just distracts the eye from
> ready the actual method name. And it adds absolutely no information for
> the source code reader.

That one is indeed there only to make Checkstyle happy. The Javadoc tool
is able to retrieve by itself the javadoc from the redefined method
(Eclipse as well). I wish Checkstyle could do that too. We will be able
to partially solve that when switching to Java 1.5, by using the
@Override annotation.

Should the rule be disabled because of that? Having proper javadoc on at
least public methods is very important. OTOH, this is actually not
something Checkstyle can verify. How many methods in the code base have
totally useless comments that are there just to avoid a Checkstyle
warning...

I think I’d prefer to keep the rule, but wouldn’t veto its removal.


>> would do the trick on those,  UNLESS they implement something which is
>> unexpected (such as the equals methods I recently renamed which did
>> not implement equals) or special (a toString which creates a
>> guaranteed parsable result for example)
> 
> Hmmm. A equals method shouldn't do anything unexpected. But your
> toString() example is a good one. If such standard methods do something
> more as the comment in Object says, that a comment is useful. 
> 
> I think it's the same as on simple public methods like the getter from
> above. If your comment doesn't say anything more than the method name
> says already, I don't want to read it.
> 
> Best Regards
> Alex

Vincent

Reply via email to