.
-Original Message-
From: Sylvain Lebresne [mailto:sylv...@datastax.com]
Sent: Friday, May 6, 2016 2:22 AM
To: dev@cassandra.apache.org
Subject: Re: [Proposal] Mandatory comments
> When I'm reading code i look for comments to help me understand key
points,
> points that aren't sel
> 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.
Frankly, I don't love the idea of somewhat limiting comments on purpose so
the
sheer presence of a c
My vote is to start with BigTableScanner (SSTableScanner).. 5 iterators that
all do something different with each other depending on how used with zero
comments -- in a critical code path. What could go wrong!
> On May 5, 2016, at 11:26 AM, Dave Brosius wrote:
>
> A less controversial tact wou
A less controversial tact would be to actively solicit input from
contributors, etc, about what methods/classes are confusing, and put
those classes/methods on a priority list for adding good javadoc. When
that list goes to ~0, you've probably done enough.
The key tho is to actively solicit, a
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
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 feedb
I think that Netty is a good example of comments, at least for me they
often were helpful, both from perspective of working on the code and from
user perspective (when something seems to be working not as expected, you
can usually find out reasons for it from the code in a straightforward
way).
I
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
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 sim
>
> Some consensus is needed whether there should be some rote comment for
> getters and setters, or whether the Javadoc should be simply skipped for
> simple getters and setters, provided that there is separate doc for the
> field that they name.
I think it would help if we collectively agreed up
Not so much wiggle room in that case so much as a guideline for commenting
getters and setters and the field they access.
Some consensus is needed whether there should be some rote comment for
getters and setters, or whether the Javadoc should be simply skipped for
simple getters and setters, prov
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 f
I think this is very basic. If its not followed till now, we should do that now
on.Just a suggestion.
So,there should be a rule and may be a code review checklist point to verify
that "quality" of comments is ok and comments are sufficient.
Regarding, high level comments, I feel that they are won
On Mon, May 2, 2016 at 7:16 PM, Jonathan Ellis wrote:
> What I'd like to see is more comments like the one in StreamSession:
> something that can give me the "big picture" for a piece of functionality.
>
I wholeheartedly agree that we need more of those. I don't think though that
we need a singl
+1 for some kind of (unspecified) improvement on the comment front.
+1 for updated style guide giving recommended practices for commenting
Specific rules/guidelines? So hard to get it right at an abstract level -
what can sound great in theory can fail miserably in practice. And what can
work gre
o.a.c.hints/package-info.java is a pretty good example of what that looks
like. My previous statement about dangers of comment atrophy and needing to
be diligent holds doubly-true if the comments themselves aren't localized
to the files we're touching on modification.
I see a case for better docum
What I'd like to see is more comments like the one in StreamSession:
something that can give me the "big picture" for a piece of functionality.
I wonder if focusing on class-based comments might miss an opportunity
here. StreamSession was chosen somewhat arbitrarily to be where we
described the s
I've been discouraged from contributing to the codebase due to it's lack of
comments, so I +1 this big time.
Some people argue against comments by saying "the code should be self
describing", but that misses the point. The comments should describe the
*intent* of the code, the problem it's mean t
Fighting comment atrophy will become a more pressing concern for us in the
future if we standardize this so we might want to add something about that
in CodeStyle as well. This is fundamental best-practices behavior for the
maintainability of a complex code-base with multiple contributors so I'm
st
There could be disagreement on this, but I think that we are in general not
very good at commenting Cassandra code and I would suggest that we make a
collective effort to improve on this. And to help with that goal, I would
like
to suggest that we add the following rule to our code style guide
(htt
20 matches
Mail list logo
