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
