On Sun, Jan 30, 2011 at 4:47 PM, Maciej Stachowiak <m...@apple.com> wrote:
> Well, I didn't mean to pick on the authors of this file. This is the > impression I get from a lot of code that some call "well-commented", by > which they mean "lots of comments". > I agree that the comments you pointed out are pretty unhelpful. I tried to emphasize already that silly comments that just restate the next line of code are not at all what I mean by "well commented", and that what I am interested in are comments about subtle but crucial details (e.g. complex ownership rules) or comments that sum up a huge swath of source code (e.g. a class-level comment that covers the critical high-level points the class is responsible for). I honestly don't think there is much disagreement about what kinds of comments are unhelpful. I think the disagreement here comes from past experience, where some people have mostly experienced low-quality and out-of-date comments and are justifiably uninterested in repeating that, and others have been helped by high-quality comments in complex codebases and want to see more of that in WebKit. It seems like the best rule of thumb would be that reviewers should look at any added comments and judge whether the comments are really valuable. I don't think we need to (or should) globally frown on comments -- just on bad comments. PK
_______________________________________________ webkit-dev mailing list webkit-dev@lists.webkit.org http://lists.webkit.org/mailman/listinfo.cgi/webkit-dev