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

> On Thu, Jan 27, 2011 at 3:46 PM, Eric Seidel <e...@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 <da...@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





_______________________________________________
webkit-dev mailing list
webkit-dev@lists.webkit.org
http://lists.webkit.org/mailman/listinfo.cgi/webkit-dev

Reply via email to