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<sylv...@datastax.com> wrote: 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 >
