On 07/06/2012 11:41 AM, Ryosuke Niwa wrote:
Indeed, we try to avoid adding comments as much as possible since
comments tend to get out-of-date very quickly, we don't want to be
spending all our time updating comments.
Heavens forbid that someone who actually understands the code should have
to update the comments once in a while. Better to keep it inscrutable
so newbies spend all of *their* time trying to figure it all out.
Instead, we try to refactor
code so that code is self-evident or add assertions to codify the comments.
You're deluding yourself if you think the code (or any code this large and
complicated) is or can be self-evident. I find it quite painful to
figure out
my way through the WebKit code-base, and I'm hardly inexperienced.
The biggest annoyance I found is lack of class-level comments. For example
what is an Interpreter? How many instances are there in the system?
(I.e. is it a singleton class? Is there one per window? One per thread?)
What is the relationship to JSGlobalData, JSGlobalObject, RootObject.
There are a lot of these classes, and it takes quite a bit of staring at
the code to figure it out. Worse, it's hard to remember it all, so if I
come back to the codebase after working on something else I have to
figure out all out again: I might remember some aspects (like a class
starting with JS is probably some kind of JavaScript object), but not
a lot of other relationships and properties of the classes.
Those of you who work on WebKit all the time might be comfortable
with the lack of comments, but I think it's a misguided and unfriendly
policy.
Of course sometimes I fail to comments classes and functions where I should,
but I understand that's a bug, not a feature,
--
--Per Bothner
per.both...@oracle.com p...@bothner.com http://per.bothner.com/
_______________________________________________
webkit-dev mailing list
webkit-dev@lists.webkit.org
http://lists.webkit.org/mailman/listinfo.cgi/webkit-dev
