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. -- Jonathan Ellis Project Chair, Apache Cassandra co-founder, http://www.datastax.com @spyced
