Re: [Proposal] Mandatory comments
On Wed, May 4, 2016 at 12:14 PM, Jonathan Ellis wrote: > On Wed, May 4, 2016 at 2:27 AM, Sylvain Lebresne > wrote: > >> On Tue, May 3, 2016 at 6:57 PM, Eric Evans >> wrote: >> >> > On Mon, May 2, 2016 at 11:26 AM, Sylvain Lebresne >> > 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. This. Additionally you could also probably argue that it obscures the true purpose to leaving a comment; It becomes a check box to tick, having some javadoc attached to every method, rather than genuinely looking for the value that could be added with quality comments (or even altering the approach so that the code is more obvious in the absence of them). The reason I suggested "wiggle room", is that I think everyone basically agrees that the default should be to leave good comments (and that that hasn't been the case), that we should start making this a requirement to successful review, and that we can afford to leave some room for judgment on the part of the reviewer. Worse-case is that we find in doing so that there isn't much common ground on what constitutes a quality comment versus useless boilerplate, and that we have to remove any wiggle room and make it 100% mandatory (I don't think that will (has to) be the case, though). -- Eric Evans john.eric.ev...@gmail.com
Re: [Proposal] Mandatory comments
FWIW, I recently wrote up a bunch of notes on Code Quality and published them on Medium. There are notes on comments and consistency and boilerplate buried in there. WARNING: There's a lot of stuff there and it is not for the faint of heart or those not truly committed to code quality. tl;dr - I'm not a fan of boiler plate just to say you did something, but... I am a fan of consistency, but that doesn't mean every situation is the same, just that similar situations should be treated similarly - unless there is some reasonable reason to do otherwise. See: https://medium.com/@jackkrupansky/code-quality-preamble-932626a3131c#.ynrjbryus https://medium.com/@jackkrupansky/software-and-product-quality-notes-no-1-346ab1d8df24#.xzg1ihuxb https://medium.com/@jackkrupansky/code-quality-notes-no-1-4dc522a5e29c#.cm7tan2zu https://medium.com/@jackkrupansky/code-quality-notes-no-2-7939377b73c6#.zco8oq3dj -- Jack Krupansky On Thu, May 5, 2016 at 10:55 AM, Eric Evans wrote: > On Wed, May 4, 2016 at 12:14 PM, Jonathan Ellis wrote: > > On Wed, May 4, 2016 at 2:27 AM, Sylvain Lebresne > > wrote: > > > >> On Tue, May 3, 2016 at 6:57 PM, Eric Evans > >> 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. > > This. > > Additionally you could also probably argue that it obscures the true > purpose to leaving a comment; It becomes a check box to tick, having > some javadoc attached to every method, rather than genuinely looking > for the value that could be added with quality comments (or even > altering the approach so that the code is more obvious in the absence > of them). > > The reason I suggested "wiggle room", is that I think everyone > basically agrees that the default should be to leave good comments > (and that that hasn't been the case), that we should start making this > a requirement to successful review, and that we can afford to leave > some room for judgment on the part of the reviewer. Worse-case is > that we find in doing so that there isn't much common ground on what > constitutes a quality comment versus useless boilerplate, and that we > have to remove any wiggle room and make it 100% mandatory (I don't > think that will (has to) be the case, though). > > > -- > Eric Evans > john.eric.ev...@gmail.com >
Can I replace a 2.0.9 node with a 2.1.14 node in a cluster?
Hi, due to internal infrastructure changes, we have to replace all nodes with new nodes. All the existing nodes are running Cassandra Community version 2.0.9. I was thinking may be this is also an opportunity for us to upgrade to Cassandra Community version 2.1.14. I hope I am not asking a crazy question: But can I replace a 2.0.9 node with a 2.1.14 node in the cluster, i.e. can 2.0.9 nodes and 2.1.14 nodes work peacefully together in a cluster if I replace 2.0.9 nodes with 2.1.14 nodes one by one? Thanks. George.
Re: [Proposal] Mandatory comments
A less controversial tact would be to actively solicit input from contributors, etc, about what methods/classes are confusing, and put those classes/methods on a priority list for adding good javadoc. When that list goes to ~0, you've probably done enough. The key tho is to actively solicit, and make it easy to do so. It's important to differentiate the list being 0 because you've done a good job, and 0 because people didn't know about it, or was to difficult to ask for. --dave --- On 2016-05-05 11:46, Jack Krupansky wrote: FWIW, I recently wrote up a bunch of notes on Code Quality and published them on Medium. There are notes on comments and consistency and boilerplate buried in there. WARNING: There's a lot of stuff there and it is not for the faint of heart or those not truly committed to code quality. tl;dr - I'm not a fan of boiler plate just to say you did something, but... I am a fan of consistency, but that doesn't mean every situation is the same, just that similar situations should be treated similarly - unless there is some reasonable reason to do otherwise. See: https://medium.com/@jackkrupansky/code-quality-preamble-932626a3131c#.ynrjbryus https://medium.com/@jackkrupansky/software-and-product-quality-notes-no-1-346ab1d8df24#.xzg1ihuxb https://medium.com/@jackkrupansky/code-quality-notes-no-1-4dc522a5e29c#.cm7tan2zu https://medium.com/@jackkrupansky/code-quality-notes-no-2-7939377b73c6#.zco8oq3dj -- Jack Krupansky On Thu, May 5, 2016 at 10:55 AM, Eric Evans wrote: On Wed, May 4, 2016 at 12:14 PM, Jonathan Ellis wrote: > On Wed, May 4, 2016 at 2:27 AM, Sylvain Lebresne > wrote: > >> On Tue, May 3, 2016 at 6:57 PM, Eric Evans >> 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. This. Additionally you could also probably argue that it obscures the true purpose to leaving a comment; It becomes a check box to tick, having some javadoc attached to every method, rather than genuinely looking for the value that could be added with quality comments (or even altering the approach so that the code is more obvious in the absence of them). The reason I suggested "wiggle room", is that I think everyone basically agrees that the default should be to leave good comments (and that that hasn't been the case), that we should start making this a requirement to successful review, and that we can afford to leave some room for judgment on the part of the reviewer. Worse-case is that we find in doing so that there isn't much common ground on what constitutes a quality comment versus useless boilerplate, and that we have to remove any wiggle room and make it 100% mandatory (I don't think that will (has to) be the case, though). -- Eric Evans john.eric.ev...@gmail.com
Re: [Proposal] Mandatory comments
My vote is to start with BigTableScanner (SSTableScanner).. 5 iterators that all do something different with each other depending on how used with zero comments -- in a critical code path. What could go wrong! > On May 5, 2016, at 11:26 AM, Dave Brosius wrote: > > A less controversial tact would be to actively solicit input from > contributors, etc, about what methods/classes are confusing, and put those > classes/methods on a priority list for adding good javadoc. When that list > goes to ~0, you've probably done enough. > > The key tho is to actively solicit, and make it easy to do so. It's important > to differentiate the list being 0 because you've done a good job, and 0 > because people didn't know about it, or was to difficult to ask for. > > --dave > > --- > > > On 2016-05-05 11:46, Jack Krupansky wrote: >> FWIW, I recently wrote up a bunch of notes on Code Quality and published >> them on Medium. There are notes on comments and consistency and boilerplate >> buried in there. >> WARNING: There's a lot of stuff there and it is not for the faint of heart >> or those not truly committed to code quality. >> tl;dr - I'm not a fan of boiler plate just to say you did something, but... >> I am a fan of consistency, but that doesn't mean every situation is the >> same, just that similar situations should be treated similarly - unless >> there is some reasonable reason to do otherwise. >> See: >> https://medium.com/@jackkrupansky/code-quality-preamble-932626a3131c#.ynrjbryus >> https://medium.com/@jackkrupansky/software-and-product-quality-notes-no-1-346ab1d8df24#.xzg1ihuxb >> https://medium.com/@jackkrupansky/code-quality-notes-no-1-4dc522a5e29c#.cm7tan2zu >> https://medium.com/@jackkrupansky/code-quality-notes-no-2-7939377b73c6#.zco8oq3dj >> -- Jack Krupansky >> On Thu, May 5, 2016 at 10:55 AM, Eric Evans >> wrote: >>> On Wed, May 4, 2016 at 12:14 PM, Jonathan Ellis wrote: >>> > On Wed, May 4, 2016 at 2:27 AM, Sylvain Lebresne >>> > wrote: >>> > >>> >> On Tue, May 3, 2016 at 6:57 PM, Eric Evans >>> >> 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. >>> This. >>> Additionally you could also probably argue that it obscures the true >>> purpose to leaving a comment; It becomes a check box to tick, having >>> some javadoc attached to every method, rather than genuinely looking >>> for the value that could be added with quality comments (or even >>> altering the approach so that the code is more obvious in the absence >>> of them). >>> The reason I suggested "wiggle room", is that I think everyone >>> basically agrees that the default should be to leave good comments >>> (and that that hasn't been the case), that we should start making this >>> a requirement to successful review, and that we can afford to leave >>> some room for judgment on the part of the reviewer. Worse-case is >>> that we find in doing so that there isn't much common ground on what >>> constitutes a quality comment versus useless boilerplate, and that we >>> have to remove any wiggle room and make it 100% mandatory (I don't >>> think that will (has to) be the case, though). >>> -- >>> Eric Evans >>> john.eric.ev...@gmail.com
