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 <jbel...@gmail.com> wrote: > On Wed, May 4, 2016 at 2:27 AM, Sylvain Lebresne <sylv...@datastax.com> > wrote: > > > On Tue, May 3, 2016 at 6:57 PM, Eric Evans <john.eric.ev...@gmail.com> > > wrote: > > > > > On Mon, May 2, 2016 at 11:26 AM, Sylvain Lebresne < > sylv...@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 > --
