[webkit-dev] coding style and comments

[Darin Adler]

On the WebKit project we like “why” comments, but not “what” comments. Comments that say what the next block of code does usually are not a good idea. Instead by using appropriate names and granularity we want the code itself to say what the comment would have.

We also frown on “textbook” style comments. Long block comments that read like a manifesto about what a code or class will do aren’t typical in WebKit.

It’s critical that comments contain information that the code does not, rather than repeating information that is already present in the code. And that comments are brief enough and easy enough to read that they are likely to be noticed and updated as the code changes.

I don’t think this has much to do with specific programming languages.

A good discussion of comments could revolve around some specific code sequences and a discussion of whether a particular comment is suitable. I’m not sure we can get very far in the abstract.

    -- Darin

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