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

Attachment: signature.asc
Description: This is a digitally signed message part

Reply via email to