I've been discouraged from contributing to the codebase due to it's lack of comments, so I +1 this big time.
Some people argue against comments by saying "the code should be self describing", but that misses the point. The comments should describe the *intent* of the code, the problem it's mean to solve, not what it does. It's hard to look at code with a bug and ask yourself "what is this supposed to do?", that should have already been answered for you. On Mon, May 2, 2016 at 9:40 AM Josh McKenzie <jmcken...@apache.org> wrote: > 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 > > >
