FWIW, I recently wrote up a bunch of notes on Code Quality and published them on Medium. There are notes on comments and consistency and boilerplate buried in there.
WARNING: There's a lot of stuff there and it is not for the faint of heart or those not truly committed to code quality. tl;dr - I'm not a fan of boiler plate just to say you did something, but... I am a fan of consistency, but that doesn't mean every situation is the same, just that similar situations should be treated similarly - unless there is some reasonable reason to do otherwise. See: https://medium.com/@jackkrupansky/code-quality-preamble-932626a3131c#.ynrjbryus https://medium.com/@jackkrupansky/software-and-product-quality-notes-no-1-346ab1d8df24#.xzg1ihuxb https://medium.com/@jackkrupansky/code-quality-notes-no-1-4dc522a5e29c#.cm7tan2zu https://medium.com/@jackkrupansky/code-quality-notes-no-2-7939377b73c6#.zco8oq3dj -- Jack Krupansky On Thu, May 5, 2016 at 10:55 AM, Eric Evans <john.eric.ev...@gmail.com> wrote: > 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 >
