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