On the WebKit project we like “why” comments, but not “what” comments. Comments
that say what the next block of code does usually are not a good idea. Instead
by using appropriate names and granularity we want the code itself to say what
the comment would have.
We also frown on “textbook” style comments. Long block comments that read like
a manifesto about what a code or class will do aren’t typical in WebKit.
It’s critical that comments contain information that the code does not, rather
than repeating information that is already present in the code. And that
comments are brief enough and easy enough to read that they are likely to be
noticed and updated as the code changes.
I don’t think this has much to do with specific programming languages.
A good discussion of comments could revolve around some specific code sequences
and a discussion of whether a particular comment is suitable. I’m not sure we
can get very far in the abstract.
-- Darin
_______________________________________________
webkit-dev mailing list
webkit-dev@lists.webkit.org
http://lists.webkit.org/mailman/listinfo.cgi/webkit-dev
