[webkit-dev] Please include function-level comments in change log entries

[Per Bothner]

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.bothner at oracle.com   per at bothner.com   http://per.bothner.com/