[webkit-dev] coding style and comments

Maciej Stachowiak mjs at apple.com
Sun Jan 30 16:42:55 PST 2011

On Jan 28, 2011, at 11:34 AM, Maciej Stachowiak wrote:

> In general, I agree with what Eric and Darin said about this topic.

By the way, here are some good resources that align well with the traditional WebKit project philosophy of commenting:

My new favorite statement about this topic is, "If you can turn a comment into source code, do it." When adding a comment, try to think - why is this code so unclear that it needs a comment? Is there a way to rewrite it so the source speaks for itself? <http://www.c2.com/cgi/wiki?TreatCommentsWithSuspicion>

More on potential downsides of comments, and how refactoring can be an alternative: <http://www.c2.com/cgi/wiki?ToNeedComments>

Here are some good techniques for making code more naturally self-documenting: <http://www.c2.com/cgi/wiki?SelfDocumentingCode>

Here is a criticism specifically of giant block comments: <http://www.c2.com/cgi/wiki?MassiveFunctionHeaders>

And here is a an argument for "why not what" commenting: <http://www.c2.com/cgi/wiki?CommentTheWhy>


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

More information about the webkit-dev mailing list