[webkit-dev] coding style and comments

[Peter Kasting]

On Sun, Jan 30, 2011 at 4:47 PM, Maciej Stachowiak <mjs at apple.com> wrote:

> Well, I didn't mean to pick on the authors of this file. This is the
> impression I get from a lot of code that some call "well-commented", by
> which they mean "lots of comments".
>

I agree that the comments you pointed out are pretty unhelpful.  I tried to
emphasize already that silly comments that just restate the next line of
code are not at all what I mean by "well commented", and that what I am
interested in are comments about subtle but crucial details (e.g. complex
ownership rules) or comments that sum up a huge swath of source code (e.g. a
class-level comment that covers the critical high-level points the class is
responsible for).

I honestly don't think there is much disagreement about what kinds of
comments are unhelpful.  I think the disagreement here comes from past
experience, where some people have mostly experienced low-quality and
out-of-date comments and are justifiably uninterested in repeating that, and
others have been helped by high-quality comments in complex codebases and
want to see more of that in WebKit.

It seems like the best rule of thumb would be that reviewers should look at
any added comments and judge whether the comments are really valuable.  I
don't think we need to (or should) globally frown on comments -- just on bad
comments.

PK
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.webkit.org/pipermail/webkit-dev/attachments/20110131/ecd69ab4/attachment.html>