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. Anyway, I have no intention of being an ass and rejecting a well commented patch during review just because it missing a javadoc on a setFoo(int) method. But I do intend to try to follow the rule strictly and I think it'll be simpler if everyone does too. If nothing else, it'll bring consistency and that's reassuring for newcomers. -- Sylvain
