[webkit-dev] coding style and comments

[Maciej Stachowiak]

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>


Regards,
Maciej

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