[webkit-dev] coding style and comments
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...
More information about the webkit-dev