RE: [Proposal] Mandatory comments

. -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 self-evident.

Re: [Proposal] Mandatory comments

> 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

Re: [Proposal] Mandatory comments

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

Re: [Proposal] Mandatory comments

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,

Re: [Proposal] Mandatory comments

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 -

Re: [Proposal] Mandatory comments

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

Re: [Proposal] Mandatory comments

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

Re: [Proposal] Mandatory comments

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

Re: [Proposal] Mandatory comments

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

Re: [Proposal] Mandatory comments

> > 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

Re: [Proposal] Mandatory comments

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,

Re: [Proposal] Mandatory comments

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

Re: [Proposal] Mandatory comments

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

Re: [Proposal] Mandatory comments

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

Re: [Proposal] Mandatory comments

+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

Re: [Proposal] Mandatory comments

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

Re: [Proposal] Mandatory comments

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

Re: [Proposal] Mandatory comments

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

Re: [Proposal] Mandatory comments

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

[Proposal] Mandatory comments

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