On Thu, Jan 27, 2011 at 7:27 PM, Simon Fraser <simon.fra...@apple.com> wrote: > > I think we have a distinct lack of comments that help novices to understand > the code. I feel that we almost have a "privileged few" mentality in some > code; if you can't figure it out by reading the code, then you shouldn't be > messing with it.
As a WebKit porter who has not yet seriously dug into the WebCore code much beyond platform I tend to get the same feeling as Simon. While a web engine is not a trivial piece of code some parts of WebKit are much more obtuse to non-experts and could benefit from a little more commenting. When trying to debug problems in a port it is very easy to get lost and confused when in WebCore code. Now maybe that is just the nature of the beast and it takes time to grok, but surely there could be some small improvements made with a few comments. > So I encourage more comments (and use them fairly copiously, for anything > non-obvious, in my own code). I'd particularly encourage comments before > each class definition that say what the class is for, what its lifetime is, > what the ownership model is, and how many are usually instantiated. +1000! When doing my port for Haiku I was obviously mostly dealing with platform classes and I wrote comments in my build file about what I thought each platform file was for (some are not so obvious, I still don't know why there is both a Pasteboard and a Clipboard.) I think it gets much worse deeper inside WebCore. So I think it could really help new contributors (or anyone really) to have some high-level comments for classes just like Simon says above. -- Regards, Ryan _______________________________________________ webkit-dev mailing list webkit-dev@lists.webkit.org http://lists.webkit.org/mailman/listinfo.cgi/webkit-dev
