[webkit-dev] coding style and comments

[Maciej Stachowiak]

On Jan 30, 2011, at 4:41 PM, Ryan Leavengood wrote:

> On Sunday, January 30, 2011, Maciej Stachowiak <mjs at apple.com> wrote:
>> 
>> I'll go the other way and point out some example of comments that I think are poor.
> 
> This file is terribly commented, I agree, but cherry picking a really
> bad file isn't the best way to make a point IMO.

Well, I didn't mean to pick on the authors of this file. This is the impression I get from a lot of code that some call "well-commented", by which they mean "lots of comments". 

> Maybe the solution here is better documentation outside the source
> code. I hope some of the more experienced WebKit developers can agree
> that there are parts of the code that are harder for new developers to
> dig into. Some high-level docs that are kept updated might be nice. Of
> course the key here is keeping them updated, and if it is hard to keep
> source code comments up to date I don't know how much hope there is
> for outside docs. Of course this applies to any project and is by no
> means just a flaw in this project. At least if the comments are in the
> code there is hope that a reviewer would catch when comments get out
> of date.

I agree that high-level docs would be useful. It's hard to make good ones. My favorite two kinds of non-source-code documentation are explanations of common idioms (e.g. <http://webkit.org/coding/RefPtr.html>) and explanations of how large-scale subsystems relate to each other. These types of documentation are somewhat less likely to go out of date than function-level or even class-level comments. Often, the best place for them is not in the code. Though it might be a good comprehensive guide to WebKit development that collects the more useful documentation we have.

Regards,
Maciej

-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.webkit.org/pipermail/webkit-dev/attachments/20110130/f8ef33a8/attachment.html>