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
