On Mon, May 2, 2016 at 7:16 PM, Jonathan Ellis <jbel...@gmail.com> 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 <sylv...@datastax.com>
> 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
>
