[webkit-dev] coding style and comments

Peter Kasting pkasting at chromium.org
Mon Jan 31 11:01:40 PST 2011

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

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

More information about the webkit-dev mailing list