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