cassandra-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Josh McKenzie <jmcken...@apache.org>
Subject Re: [Proposal] Mandatory comments
Date Mon, 02 May 2016 17:29:39 GMT
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 <jbellis@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 <sylvain@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
>

Mime
  • Unnamed multipart/alternative (inline, None, 0 bytes)
View raw message