+1 for some kind of (unspecified) improvement on the comment front. +1 for updated style guide giving recommended practices for commenting
Specific rules/guidelines? So hard to get it right at an abstract level - what can sound great in theory can fail miserably in practice. And what can work great initially, when people are all excited about it, can slowly rot as that initial enthusiasm fades. How to start? Suggestion: Instead of trying to seek consensus on abstract rules/guidelines, just randomly pick some module that is in need of better comments and have dueling patches for how to best comment it. And then once the dust settles and there is some general consensus on what the real/implied rules/guidelines should be, based on the reality of that initial module, pick another module.and see if the deduced rules/guidelines from the first module can be methodically applied. -- Jack Krupansky On Mon, May 2, 2016 at 1:29 PM, Josh McKenzie <jmcken...@apache.org> wrote: > 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 > > >
