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

[Eric Seidel]

Per:

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
>> 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/
>
>
> _______________________________________________
> webkit-dev mailing list
> webkit-dev at lists.webkit.org
> http://lists.webkit.org/mailman/listinfo.cgi/webkit-dev