cassandra-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Jonathan Ellis <jbel...@gmail.com>
Subject Re: [Proposal] Mandatory comments
Date Wed, 04 May 2016 17:14:25 GMT
On Wed, May 4, 2016 at 2:27 AM, Sylvain Lebresne <sylvain@datastax.com>
wrote:

> On Tue, May 3, 2016 at 6:57 PM, Eric Evans <john.eric.evans@gmail.com>
> wrote:
>
> > On Mon, May 2, 2016 at 11:26 AM, Sylvain Lebresne <sylvain@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.

-- 
Jonathan Ellis
Project Chair, Apache Cassandra
co-founder, http://www.datastax.com
@spyced

Mime
  • Unnamed multipart/alternative (inline, None, 0 bytes)
View raw message