Not so much wiggle room in that case so much as a guideline for commenting getters and setters and the field they access.
Some consensus is needed whether there should be some rote comment for getters and setters, or whether the Javadoc should be simply skipped for simple getters and setters, provided that there is separate doc for the field that they name. I'm not sure what the best way is to document or distinguish a private field vs. a pseudo-field whose getters and setters are implemented by calling methods rather than merely returning or setting the private field. I mean, you don't want to clutter the public Javadoc with details of every private field, but those private fields that have getters and setters clearly need to be documented - at least in terms that will make sense to the users of the getters and setters. One alternative is to document the field/pseudo-field on either the getter or the setter with a "See..." linked on the other. I mean, if you are looking at the code for one, you should be able to quickly get to the doc for the field/pseudo-field itself. And if there are any special rules or checks in the setter, they should have Javadoc, either for the setter or the field. -- Jack Krupansky On Tue, May 3, 2016 at 12:57 PM, Eric Evans <john.eric.ev...@gmail.com> wrote: > On Mon, May 2, 2016 at 11:26 AM, Sylvain Lebresne <sylv...@datastax.com> > wrote: > > Looking forward to other's opinions and feedbacks on this proposal. > > We might want to leave just a little wiggle room for judgment on the > part of the reviewer, for the very simple cases. Documenting > something like setFoo(int) with "Sets foo" can get pretty tiresome for > everyone, and doesn't add any value. > > Otherwise I think this is perfectly reasonable; +1 > > > -- > Eric Evans > john.eric.ev...@gmail.com >
