cassandra-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Eric Evans <>
Subject Re: [Proposal] Mandatory comments
Date Thu, 05 May 2016 14:55:48 GMT
On Wed, May 4, 2016 at 12:14 PM, Jonathan Ellis <> wrote:
> On Wed, May 4, 2016 at 2:27 AM, Sylvain Lebresne <>
> wrote:
>> On Tue, May 3, 2016 at 6:57 PM, Eric Evans <>
>> wrote:
>> > On Mon, May 2, 2016 at 11:26 AM, Sylvain Lebresne <>
>> > 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.


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

View raw message