Mailing-List: contact dev-help@cassandra.apache.org; run by ezmlm
Precedence: bulk
Reply-To: dev@cassandra.apache.org
MIME-Version: 1.0
In-Reply-To: <CAEHpzv_WK5Q7BCgVksXVLgUnJOZmsvHEHSv2xug=16E=D5eM6A@mail.gmail.com>
References: <CAKkz8Q088OJbvhYCyZ2_2Eotqk4y-SVWiwkSinPT6Rr9PoPKtQ@mail.gmail.com>
 <CAEHpzv_WK5Q7BCgVksXVLgUnJOZmsvHEHSv2xug=16E=D5eM6A@mail.gmail.com>
From: Sylvain Lebresne <sylvain@datastax.com>
Date: Wed, 4 May 2016 09:27:01 +0200
Message-ID: <CAKkz8Q2QFCY-JHyfA5TCMW+ErW5tz3awz06n65AvtEPtFK1_nA@mail.gmail.com>
Subject: Re: [Proposal] Mandatory comments
To: "dev@cassandra.apache.org" <dev@cassandra.apache.org>
Content-Type: multipart/alternative; boundary=001a114d747c01241a0531ff28a5
archived-at: Wed, 04 May 2016 07:27:33 -0000

--001a114d747c01241a0531ff28a5
Content-Type: text/plain; charset=UTF-8

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.

Anyway, I have no intention of being an ass and rejecting a well commented
patch during review
just because it missing a javadoc on a setFoo(int) method. But I do intend
to try to follow the rule
strictly and I think it'll be simpler if everyone does too. If nothing
else, it'll bring consistency and
that's reassuring for newcomers.

--
Sylvain

--001a114d747c01241a0531ff28a5--