[webkit-dev] coding style and comments
mjs at apple.com
Sun Jan 30 16:47:45 PST 2011
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.
-------------- next part --------------
An HTML attachment was scrubbed...
More information about the webkit-dev