[webkit-dev] Please include function-level comments in change log entries
eric at webkit.org
Fri Jul 6 13:02:39 PDT 2012
You began by thread-jacking Dan's discussion of ChangeLogs, and now
appear to be attacking a seasoned contributors polite response with
sarcasm and derision.
I recommend you soften your words, and try again on another thread.
Commenting, or lack there of, has been discussed at great length on
previous webkit-dev threads. I'm sure there are many things we could
continue to discuss, but I recommend doing so in a friendlier tone, on
a separate thread.
I would recommend that we close this thread, Dan's original email was
simple a Public Service Announcement.
Thank you all, and happy hacking!
On Fri, Jul 6, 2012 at 12:54 PM, Per Bothner <per.bothner at oracle.com> wrote:
> 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
> 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
> 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
> 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
> 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/
> webkit-dev mailing list
> webkit-dev at lists.webkit.org
More information about the webkit-dev