I think this is very basic. If its not followed till now, we should do that now
on.Just a suggestion.
So,there should be a rule and may be a code review checklist point to verify
that "quality" of comments is ok and comments are sufficient.
Regarding, high level comments, I feel that they are won
On Mon, May 2, 2016 at 7:16 PM, Jonathan Ellis 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 wholeheartedly agree that we need more of those. I don't think though that
we need a singl
+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 gre
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 docum
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 s
I've been discouraged from contributing to the codebase due to it's lack of
comments, so I +1 this big time.
Some people argue against comments by saying "the code should be self
describing", but that misses the point. The comments should describe the
*intent* of the code, the problem it's mean t
Fighting comment atrophy will become a more pressing concern for us in the
future if we standardize this so we might want to add something about that
in CodeStyle as well. This is fundamental best-practices behavior for the
maintainability of a complex code-base with multiple contributors so I'm
st
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
(htt
