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