cassandra-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Oleksandr Petrov <oleksandr.pet...@gmail.com>
Subject Re: [Proposal] Mandatory comments
Date Wed, 04 May 2016 19:50:28 GMT
I think that Netty is a good example of comments, at least for me they
often were helpful, both from perspective of working on the code and from
user perspective (when something seems to be working not as expected, you
can usually find out reasons for it from the code in a straightforward
way).

I definitely support the idea of "high-level comments" (someone said
Class-level ones). Alongside, some fields might be good to describe,
especially if they have multiple purposes. If methods have conceptual
names, they're also worth commenting. All parts where protocol is implied
may reference where one could lookup how certain things are serialized
(more applicable for the collections, probably).

I can bring up several examples from top of my head of the things I could
volunteer to start commenting straight away: NativeCell (could be helpful
to document the protocol format there), CollectionSerializer, CellPath
serializer, ModificationStatement and things related to CAS, things like
values and bounds as clustering in Restrictions (and maybe recently
refactored Restriction hierarchy in general), Value (Terminal) classes in
collections, Markers, Operations, Column Conditions, DataLimits,
ColumnFamilyStore (or at least parts of it), Memtable.

Sorry for the lengthy list: it was something I stumbled upon recently, and
gladly having tests and navigating through the code helped to understand
what is going on in majority of cases.

But I wanted to bring up several positive examples as well: Cell class is
very well documented, describing it's purpose and the protocol format,
UnfilteredSerializer is quite good in terms of the protocol and overall
description, too, DataRange (describes some "tricks", too),
CqlSStableWriter, SSTable. There are many more examples, too.

So definitely count me in on improving comments. I like writing (as you can
note from the length of this email), so I'd be also very happy to help to
improve.



On Wed, May 4, 2016 at 7:21 PM Jonathan Ellis <jbellis@gmail.com> wrote:

> On Wed, May 4, 2016 at 2:27 AM, Sylvain Lebresne <sylvain@datastax.com>
> wrote:
>
> > On Tue, May 3, 2016 at 6:57 PM, Eric Evans <john.eric.evans@gmail.com>
> > wrote:
> >
> > > On Mon, May 2, 2016 at 11:26 AM, Sylvain Lebresne <
> sylvain@datastax.com>
> > > wrote:
> > > > Looking forward to other's opinions and feedbacks on this proposal.
> > >
> > > We might want to leave just a little wiggle room for judgment on the
> > > part of the reviewer, for the very simple cases.  Documenting
> > > something like setFoo(int) with "Sets foo" can get pretty tiresome for
> > > everyone, and doesn't add any value.
> > >
> >
> > I knew someone was going to bring this :). In principle, I don't really
> > disagree. In practice though,
> > I suspect it's sometimes just easier to adhere to such simple rule
> somewhat
> > strictly. In particular,
> > I can guarantee that we don't all agree where the border lies between
> what
> > warrants a javadoc
> > and what doesn't. Sure, there is a few cases where you're just
> paraphrasing
> > the method name
> > (and while it might often be the case for getters and setters, it's worth
> > noting that we don't really
> > do much of those in C*), but how hard is it to write a one line comment?
> > Surely that's a negligeable
> > part of writing a patch and we're not that lazy.
> >
>
> I'm more concerned that this kind of boilerplate commenting obscures rather
> than clarifies.  When I'm reading code i look for comments to help me
> understand key points, points that aren't self-evident.  If we institute a
> boilerplate "comment everything" rule then I lose that signpost.
>
> --
> Jonathan Ellis
> Project Chair, Apache Cassandra
> co-founder, http://www.datastax.com
> @spyced
>
--

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