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 <dbros...@mebigfatguy.com> 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 > > --- > <br type="_moz" /> > > 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 <john.eric.ev...@gmail.com> >> wrote: >>> On Wed, May 4, 2016 at 12:14 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. >>> 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
