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
_______________________________________________ webkit-dev mailing list [email protected] http://lists.webkit.org/mailman/listinfo.cgi/webkit-dev
