[webkit-dev] coding style and comments

[Simon Fraser]

On Jan 27, 2011, at 3:55 PM, Ryosuke Niwa wrote:

> On Thu, Jan 27, 2011 at 3:46 PM, Eric Seidel <eric at webkit.org> wrote:
> My personal preference (and I'd love to hear from other contributors)
> is that code should ideally be self-documenting.
> 
> I strongly agree with this point.  One pit-fall of adding comments is that it gives an illusion of the increased readability.  And I believe making code self-evident to avoid adding comments has been a good driving force in cleanup / refactoring WebKit's code base.
> 
> On Thu, Jan 27, 2011 at 3:46 PM, Darin Adler <darin at apple.com> wrote:
> We also frown on “textbook” style comments. Long block comments that read like a manifesto about what a code or class will do aren’t typical in WebKit.
> 
> I agree that WebKit code base doesn't usually have a block comment for a class, function, etc... and new code should follow that convention.

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.

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.

Simon





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