On Wed, May 4, 2016 at 12:14 PM, Jonathan Ellis <jbel...@gmail.com> wrote: > On Wed, May 4, 2016 at 2:27 AM, Sylvain Lebresne <sylv...@datastax.com> > wrote: > >> On Tue, May 3, 2016 at 6: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. >> > >> >> I knew someone was going to bring this :). In principle, I don't really >> disagree. In practice though, >> I suspect it's sometimes just easier to adhere to such simple rule somewhat >> strictly. In particular, >> I can guarantee that we don't all agree where the border lies between what >> warrants a javadoc >> and what doesn't. Sure, there is a few cases where you're just paraphrasing >> the method name >> (and while it might often be the case for getters and setters, it's worth >> noting that we don't really >> do much of those in C*), but how hard is it to write a one line comment? >> Surely that's a negligeable >> part of writing a patch and we're not that lazy. >> > > I'm more concerned that this kind of boilerplate commenting obscures rather > than clarifies. When I'm reading code i look for comments to help me > understand key points, points that aren't self-evident. If we institute a > boilerplate "comment everything" rule then I lose that signpost.
This. Additionally you could also probably argue that it obscures the true purpose to leaving a comment; It becomes a check box to tick, having some javadoc attached to every method, rather than genuinely looking for the value that could be added with quality comments (or even altering the approach so that the code is more obvious in the absence of them). The reason I suggested "wiggle room", is that I think everyone basically agrees that the default should be to leave good comments (and that that hasn't been the case), that we should start making this a requirement to successful review, and that we can afford to leave some room for judgment on the part of the reviewer. Worse-case is that we find in doing so that there isn't much common ground on what constitutes a quality comment versus useless boilerplate, and that we have to remove any wiggle room and make it 100% mandatory (I don't think that will (has to) be the case, though). -- Eric Evans john.eric.ev...@gmail.com
