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;
}
}
> > 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.
> 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
signature.asc
Description: This is a digitally signed message part
