Re: [Proposal] Mandatory comments

[Anuj Wadehra]

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 wonderful and often you 
can effortlessly get the low level design by reading them. The only drawback is 
their maintenance. Maintenance of "big picture" when code starts drifiting from 
it is tough. You will make an important change in class X and should take care 
that the big picture is updated at some other place. One may debate that such 
instances would be rare.

ThanksAnuj
Sent from Yahoo Mail on Android 
 
  On Tue, 3 May, 2016 at 12:26 AM, Sylvain Lebresne 
wrote:   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 single kind of comment, nor even that we're lacking on a single
kind.


>
> I wonder if focusing on class-based comments might miss an opportunity
> here.


I don't meant to imply any exclusive focusing by my suggestion. I'm
constantly
seeing classes that not well explained and methods that make complex and
undocumented assumptions, so I'm very much convinced improvements are
needed on that front. Without, again, invalidating the equal need for big
picture
comments.


>
> Is this a case for package-level javadoc, and organizing our class
> hierarchy better along those lines?
>

I agree that this would probably be the best place for those bit-picture
documentation. I'd be totally fine adding on top of the rule I suggested
another
one that says:
  - If you create a new package, you should have a package level javadoc
that
    describe the big picture of what that package is about.

I do want to note that I'm trying to focus the discussion here on a few
simple
concrete points we could hopefully easily agree on so that we improve our
ways
moving forward and I'd personally love to focus on that first. That won't
fix
existing code by itself, but the optimistic in me hopes that if we get more
consistent
quality of comments in new code, our inconfort with the lack of comments in
old
code will grow and we'll end up fixing it naturally over time.

--
Sylvain


>
> On Mon, May 2, 2016 at 11:26 AM, Sylvain Lebresne 
> wrote:
>
> > 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
> > (https://wiki.apache.org/cassandra/CodeStyle):
> >  - Every public class and method must have a quality javadoc. That
> > javadoc, on
> >    top of describing what the class/method does, should call particular
> >    attention to the assumptions that the class/method does, if any.
> >
> > And of course, we'd also start enforcing that rule by not +1ing code
> unless
> > it
> > adheres to this rule.
> >
> > Note that I'm not pretending this arguably simplistic rule will magically
> > make
> > comments perfect, it won't. It's still up to us to write good and
> complete
> > comments, and it doesn't even talk about comments within methods that are
> > important too. But I think some basic rule here would be beneficial and
> > that
> > one feels sensible to me.
> >
> > Looking forward to other's opinions and feedbacks on this proposal.
> >
> > --
> > Sylvain
> >
>
>
>
> --
> Jonathan Ellis
> Project Chair, Apache Cassandra
> co-founder, http://www.datastax.com
> @spyced
>
  

Re: [Proposal] Mandatory comments

[Sylvain Lebresne]

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 single kind of comment, nor even that we're lacking on a single
kind.


>
> I wonder if focusing on class-based comments might miss an opportunity
> here.


I don't meant to imply any exclusive focusing by my suggestion. I'm
constantly
seeing classes that not well explained and methods that make complex and
undocumented assumptions, so I'm very much convinced improvements are
needed on that front. Without, again, invalidating the equal need for big
picture
comments.


>
> Is this a case for package-level javadoc, and organizing our class
> hierarchy better along those lines?
>

I agree that this would probably be the best place for those bit-picture
documentation. I'd be totally fine adding on top of the rule I suggested
another
one that says:
  - If you create a new package, you should have a package level javadoc
that
describe the big picture of what that package is about.

I do want to note that I'm trying to focus the discussion here on a few
simple
concrete points we could hopefully easily agree on so that we improve our
ways
moving forward and I'd personally love to focus on that first. That won't
fix
existing code by itself, but the optimistic in me hopes that if we get more
consistent
quality of comments in new code, our inconfort with the lack of comments in
old
code will grow and we'll end up fixing it naturally over time.

--
Sylvain


>
> On Mon, May 2, 2016 at 11:26 AM, Sylvain Lebresne 
> wrote:
>
> > 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
> > (https://wiki.apache.org/cassandra/CodeStyle):
> >   - Every public class and method must have a quality javadoc. That
> > javadoc, on
> > top of describing what the class/method does, should call particular
> > attention to the assumptions that the class/method does, if any.
> >
> > And of course, we'd also start enforcing that rule by not +1ing code
> unless
> > it
> > adheres to this rule.
> >
> > Note that I'm not pretending this arguably simplistic rule will magically
> > make
> > comments perfect, it won't. It's still up to us to write good and
> complete
> > comments, and it doesn't even talk about comments within methods that are
> > important too. But I think some basic rule here would be beneficial and
> > that
> > one feels sensible to me.
> >
> > Looking forward to other's opinions and feedbacks on this proposal.
> >
> > --
> > Sylvain
> >
>
>
>
> --
> Jonathan Ellis
> Project Chair, Apache Cassandra
> co-founder, http://www.datastax.com
> @spyced
>

Re: [Proposal] Mandatory comments

[Jack Krupansky]

+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 great initially, when people are all excited about it, can slowly rot
as that initial enthusiasm fades.

How to start? Suggestion: Instead of trying to seek consensus on abstract
rules/guidelines, just randomly pick some module that is in need of better
comments and have dueling patches for how to best comment it. And then once
the dust settles and there is some general consensus on what the
real/implied rules/guidelines should be, based on the reality of that
initial module, pick another module.and see if the deduced rules/guidelines
from the first module can be methodically applied.

-- Jack Krupansky

On Mon, May 2, 2016 at 1:29 PM, Josh McKenzie  wrote:

> 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 documentation on all three: public API's for
> classes, classes, and package level. Each serve different and important
> purposes IMO.
>
> On Mon, May 2, 2016 at 1: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 wonder if focusing on class-based comments might miss an opportunity
> > here.  StreamSession was chosen somewhat arbitrarily to be where we
> > described the streaming life cycle.  If we focused just on describing
> each
> > class in isolation then we might miss something more valuable.
> >
> > Is this a case for package-level javadoc, and organizing our class
> > hierarchy better along those lines?
> >
> > On Mon, May 2, 2016 at 11:26 AM, Sylvain Lebresne 
> > wrote:
> >
> > > 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
> > > (https://wiki.apache.org/cassandra/CodeStyle):
> > >   - Every public class and method must have a quality javadoc. That
> > > javadoc, on
> > > top of describing what the class/method does, should call
> particular
> > > attention to the assumptions that the class/method does, if any.
> > >
> > > And of course, we'd also start enforcing that rule by not +1ing code
> > unless
> > > it
> > > adheres to this rule.
> > >
> > > Note that I'm not pretending this arguably simplistic rule will
> magically
> > > make
> > > comments perfect, it won't. It's still up to us to write good and
> > complete
> > > comments, and it doesn't even talk about comments within methods that
> are
> > > important too. But I think some basic rule here would be beneficial and
> > > that
> > > one feels sensible to me.
> > >
> > > Looking forward to other's opinions and feedbacks on this proposal.
> > >
> > > --
> > > Sylvain
> > >
> >
> >
> >
> > --
> > Jonathan Ellis
> > Project Chair, Apache Cassandra
> > co-founder, http://www.datastax.com
> > @spyced
> >
>

Re: [Proposal] Mandatory comments

[Josh McKenzie]

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 documentation on all three: public API's for
classes, classes, and package level. Each serve different and important
purposes IMO.

On Mon, May 2, 2016 at 1: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 wonder if focusing on class-based comments might miss an opportunity
> here.  StreamSession was chosen somewhat arbitrarily to be where we
> described the streaming life cycle.  If we focused just on describing each
> class in isolation then we might miss something more valuable.
>
> Is this a case for package-level javadoc, and organizing our class
> hierarchy better along those lines?
>
> On Mon, May 2, 2016 at 11:26 AM, Sylvain Lebresne 
> wrote:
>
> > 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
> > (https://wiki.apache.org/cassandra/CodeStyle):
> >   - Every public class and method must have a quality javadoc. That
> > javadoc, on
> > top of describing what the class/method does, should call particular
> > attention to the assumptions that the class/method does, if any.
> >
> > And of course, we'd also start enforcing that rule by not +1ing code
> unless
> > it
> > adheres to this rule.
> >
> > Note that I'm not pretending this arguably simplistic rule will magically
> > make
> > comments perfect, it won't. It's still up to us to write good and
> complete
> > comments, and it doesn't even talk about comments within methods that are
> > important too. But I think some basic rule here would be beneficial and
> > that
> > one feels sensible to me.
> >
> > Looking forward to other's opinions and feedbacks on this proposal.
> >
> > --
> > Sylvain
> >
>
>
>
> --
> Jonathan Ellis
> Project Chair, Apache Cassandra
> co-founder, http://www.datastax.com
> @spyced
>

Re: [Proposal] Mandatory comments

[Jonathan Ellis]

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 streaming life cycle.  If we focused just on describing each
class in isolation then we might miss something more valuable.

Is this a case for package-level javadoc, and organizing our class
hierarchy better along those lines?

On Mon, May 2, 2016 at 11:26 AM, Sylvain Lebresne 
wrote:

> 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
> (https://wiki.apache.org/cassandra/CodeStyle):
>   - Every public class and method must have a quality javadoc. That
> javadoc, on
> top of describing what the class/method does, should call particular
> attention to the assumptions that the class/method does, if any.
>
> And of course, we'd also start enforcing that rule by not +1ing code unless
> it
> adheres to this rule.
>
> Note that I'm not pretending this arguably simplistic rule will magically
> make
> comments perfect, it won't. It's still up to us to write good and complete
> comments, and it doesn't even talk about comments within methods that are
> important too. But I think some basic rule here would be beneficial and
> that
> one feels sensible to me.
>
> Looking forward to other's opinions and feedbacks on this proposal.
>
> --
> Sylvain
>



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

Re: [Proposal] Mandatory comments

[Jonathan Haddad]

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 to solve, not what it does.
It's hard to look at code with a bug and ask yourself "what is this
supposed to do?", that should have already been answered for you.

On Mon, May 2, 2016 at 9:40 AM Josh McKenzie  wrote:

> 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
> strongly +1 on this.
>
> It would help to have some examples on the CodeStyle page to go along with
> this for both a class javadoc and a method javadoc.
>
> On Mon, May 2, 2016 at 12:26 PM, Sylvain Lebresne 
> wrote:
>
> > 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
> > (https://wiki.apache.org/cassandra/CodeStyle):
> >   - Every public class and method must have a quality javadoc. That
> > javadoc, on
> > top of describing what the class/method does, should call particular
> > attention to the assumptions that the class/method does, if any.
> >
> > And of course, we'd also start enforcing that rule by not +1ing code
> unless
> > it
> > adheres to this rule.
> >
> > Note that I'm not pretending this arguably simplistic rule will magically
> > make
> > comments perfect, it won't. It's still up to us to write good and
> complete
> > comments, and it doesn't even talk about comments within methods that are
> > important too. But I think some basic rule here would be beneficial and
> > that
> > one feels sensible to me.
> >
> > Looking forward to other's opinions and feedbacks on this proposal.
> >
> > --
> > Sylvain
> >
>

Re: [Proposal] Mandatory comments

[Josh McKenzie]

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
strongly +1 on this.

It would help to have some examples on the CodeStyle page to go along with
this for both a class javadoc and a method javadoc.

On Mon, May 2, 2016 at 12:26 PM, Sylvain Lebresne 
wrote:

> 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
> (https://wiki.apache.org/cassandra/CodeStyle):
>   - Every public class and method must have a quality javadoc. That
> javadoc, on
> top of describing what the class/method does, should call particular
> attention to the assumptions that the class/method does, if any.
>
> And of course, we'd also start enforcing that rule by not +1ing code unless
> it
> adheres to this rule.
>
> Note that I'm not pretending this arguably simplistic rule will magically
> make
> comments perfect, it won't. It's still up to us to write good and complete
> comments, and it doesn't even talk about comments within methods that are
> important too. But I think some basic rule here would be beneficial and
> that
> one feels sensible to me.
>
> Looking forward to other's opinions and feedbacks on this proposal.
>
> --
> Sylvain
>

[Proposal] Mandatory comments

[Sylvain Lebresne]

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
(https://wiki.apache.org/cassandra/CodeStyle):
  - Every public class and method must have a quality javadoc. That
javadoc, on
top of describing what the class/method does, should call particular
attention to the assumptions that the class/method does, if any.

And of course, we'd also start enforcing that rule by not +1ing code unless
it
adheres to this rule.

Note that I'm not pretending this arguably simplistic rule will magically
make
comments perfect, it won't. It's still up to us to write good and complete
comments, and it doesn't even talk about comments within methods that are
important too. But I think some basic rule here would be beneficial and that
one feels sensible to me.

Looking forward to other's opinions and feedbacks on this proposal.

--
Sylvain