RE: [Proposal] Mandatory comments

[Anubhav Kale <An...@microsoft.com>]

As someone not very familiar with core codebase, I just wanted to say that the comments on top of StreamSession class are a fantastic example of how comments should be. It helped me immensely to dig into node rebuilding code. So, thank you very much to the author of those comments.

-----Original Message-----
From: Sylvain Lebresne [mailto:sylvain@datastax.com] 
Sent: Friday, May 6, 2016 2:22 AM
To: dev@cassandra.apache.org
Subject: Re: [Proposal] Mandatory comments

> 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.

Frankly, I don't love the idea of somewhat limiting comments on purpose so the sheer presence of a comment is a "signpost", which kind of imply they are fairly rare. Especially because when you write and even review code, many many things that appears self-evident because you're deep in the code really aren't when you come cold to it (and doubly so when your new to the code). So that while commenting should certainly be done intelligently (and there is such thing as too much useless comments), you should imo lean toward more rather than less commenting in general.

But also, I'm talking here about commenting public methods and classes. I certainly agree that for in-code comments you don't want to mechanically comment every other line but rather only use comments when there is some subtlety.
But I
don't see it mattering that much for classes and methods. You're not gonna read the javadoc of a method that you don't use, and if you want to use one, it's almost always nice if it has a javadoc (of course, especially if it's a "good" one). There is a few cases where that javadoc isn't really useful but no harm done either imo. Have you ever think while looking at the javadoc of a library "man I wish half of the methods had no javadoc because i'm confused which methods are important now".

But anyway, I've worked on code base that had javadoc for every public methods and classes and (again provided the comments are good) didn't ever felt that this was more confusing than helpful, so I just don't buy that it is. I don't deny that there is few public classes and methods that are trivial enough that a javadoc don't add anything. And it's not so much that I care about it in those case. It's that I think making the rule strict has more pros than cons by evacuating any debate over where the line should be for having the javadoc or not and focusing our energy elsewhere.

Another of my reasoning is that I suspect one of the main reason our code is badly commented is laziness (we all seem to agree that comments are important and that our code isn't well commented enough). My hope is that by making some minimal level of commenting mandatory, we'll be forced to stop being lazy about comments and always be reminded that we should care about them. And I hope that this will help improve the overall comment quality.

So hopefully I've explained my reasoning well enough. To sum it up, having a javadoc for every public class and method certainly isn't enough (the quality of comments is really really important in particular), but I disagree that it would hurt, I'm convinced it would be an improvement over our current status quo, and more importantly I hope it might be a useful nudge to improve our comment situation long term.

But if we can't agree on that, so be it. In that case though, is there a concrete alternative proposition to help turn around our current lack of proper commenting (I'm specfically interested in fixing our ways here, commenting existing code that isn't sufficiently commented is great and we should do it, but I feel we should maybe stop committing insufficiently commented code first)? Or do we think that having had this conversation will be enough?

--
Sylvain