[webkit-dev] coding style and comments

[Ryan Leavengood]

On Thu, Jan 27, 2011 at 7:27 PM, Simon Fraser <simon.fraser at 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