o.a.c.hints/package-info.java is a pretty good example of what that looks like. My previous statement about dangers of comment atrophy and needing to be diligent holds doubly-true if the comments themselves aren't localized to the files we're touching on modification.
I see a case for better documentation on all three: public API's for classes, classes, and package level. Each serve different and important purposes IMO. On Mon, May 2, 2016 at 1: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 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 >
