> > 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 think it would help if we collectively agreed upon what problem we're trying to solve. In my mind, the specific problem we're targeting is insufficient documentation for portions of the code-base *that are not self-explanatory on their own, *with a target audience of internal C* developers*.* So a package name by itself needs more context to understand the purpose of the package, same issue w/a class declaration for non-trivial classes, and publicly exposed methods in a class generally need an explanation as to assumptions/invariants surrounding their intended usage and why they're public. Getters, setters, trivial methods, trivial helper classes, etc - none of those really benefit from comments simply re-stating what they are, and commenting them is net negative value. Same for @params in javadocs on a method if the params are self-explanatory/clear/without assumptions or invariants. Unfortunately what constitutes "self-explanatory" varies per developer to some extent so there's certainly some risk of future debate to this approach. On Tue, May 3, 2016 at 4:27 PM, Jack Krupansky <jack.krupan...@gmail.com> wrote: > 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 > > >
