Re: [webkit-dev] coding style and comments

2011-01-31 Thread Ryosuke Niwa
On Sun, Jan 30, 2011 at 4:41 PM, Ryan Leavengood leaveng...@gmail.comwrote: 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.

Re: [webkit-dev] coding style and comments

2011-01-31 Thread Konstantin Tokarev
31.01.2011, 03:41, Ryan Leavengood leaveng...@gmail.com: 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

Re: [webkit-dev] coding style and comments

2011-01-31 Thread Peter Kasting
On Sun, Jan 30, 2011 at 4:47 PM, Maciej Stachowiak m...@apple.com wrote: 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. I agree that the comments you pointed out are

Re: [webkit-dev] coding style and comments

2011-01-31 Thread Maciej Stachowiak
On Jan 31, 2011, at 11:01 AM, Peter Kasting wrote: On Sun, Jan 30, 2011 at 4:47 PM, Maciej Stachowiak m...@apple.com wrote: 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

Re: [webkit-dev] coding style and comments

2011-01-31 Thread Peter Kasting
On Mon, Jan 31, 2011 at 12:47 PM, Maciej Stachowiak m...@apple.com wrote: On Jan 31, 2011, at 11:01 AM, Peter Kasting wrote: I think people who favor comments tend to produce a lot of exactly this kind of comment. Except in some cases its verbose multiline comments that exceed the number of

Re: [webkit-dev] coding style and comments

2011-01-31 Thread Maciej Stachowiak
On Jan 31, 2011, at 1:06 PM, Peter Kasting wrote: On Mon, Jan 31, 2011 at 12:47 PM, Maciej Stachowiak m...@apple.com wrote: On Jan 31, 2011, at 11:01 AM, Peter Kasting wrote: I think people who favor comments tend to produce a lot of exactly this kind of comment. Except in some cases its

Re: [webkit-dev] coding style and comments

2011-01-31 Thread Peter Kasting
This thread has probably gone the way of all webkit-dev threads on comments or ChangeLog files -- people's opinions vary, it turns into a bikeshed, and nothing really changes about how we code. Repeat in a year. w.r.t. ImageDecoder specifically, as I mentioned before I do agree that there are

Re: [webkit-dev] coding style and comments

2011-01-31 Thread Aaron Boodman
On Mon, Jan 31, 2011 at 7:18 PM, Peter Kasting pkast...@chromium.org wrote: P.S. I agree with you about assertions being better than comments to document pre- (and post-) conditions (where possible). Me too (where possible). - a ___ webkit-dev

Re: [webkit-dev] coding style and comments

2011-01-31 Thread Maciej Stachowiak
On Jan 31, 2011, at 7:18 PM, Peter Kasting wrote: This thread has probably gone the way of all webkit-dev threads on comments or ChangeLog files -- people's opinions vary, it turns into a bikeshed, and nothing really changes about how we code. Repeat in a year. Well, even though we didn't

Re: [webkit-dev] coding style and comments

2011-01-30 Thread David Kilzer
On Jan 28, 2011, at 9:36 AM, Peter Kasting wrote: On Thu, Jan 27, 2011 at 4:27 PM, Simon Fraser simon.fra...@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

Re: [webkit-dev] coding style and comments

2011-01-30 Thread Adam Barth
On Sun, Jan 30, 2011 at 7:40 AM, David Kilzer ddkil...@webkit.org wrote: An interesting case study would be the (still ongoing?) refactoring of the loader code over the past few months (thanks to Adam Barth and others).   Is it easier to understand now than before the refactoring started?  How

Re: [webkit-dev] coding style and comments

2011-01-30 Thread Adam Barth
As an example of a harmful comment, this comment just wasted 15 minutes of my time: http://trac.webkit.org/browser/trunk/Source/WebCore/dom/Document.h#L351 The comment was true when written (although confusing because I thought it meant that these functions are virtual so we should avoid calling

Re: [webkit-dev] coding style and comments

2011-01-30 Thread Maciej Stachowiak
I'll go the other way and point out some example of comments that I think are poor. /// // BlobResourceSynchronousLoader http://trac.webkit.org/browser/trunk/WebCore/platform/network/BlobResourceHandle.cpp?rev=69610#L72

Re: [webkit-dev] coding style and comments

2011-01-30 Thread Ryan Leavengood
On Sunday, January 30, 2011, Maciej Stachowiak m...@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. Maybe the solution

Re: [webkit-dev] coding style and comments

2011-01-30 Thread Maciej Stachowiak
On Jan 28, 2011, at 11:34 AM, Maciej Stachowiak wrote: In general, I agree with what Eric and Darin said about this topic. By the way, here are some good resources that align well with the traditional WebKit project philosophy of commenting: My new favorite statement about this topic

Re: [webkit-dev] coding style and comments

2011-01-30 Thread Maciej Stachowiak
On Jan 30, 2011, at 4:41 PM, Ryan Leavengood wrote: On Sunday, January 30, 2011, Maciej Stachowiak m...@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

Re: [webkit-dev] coding style and comments

2011-01-28 Thread Peter Kasting
On Thu, Jan 27, 2011 at 4:27 PM, Simon Fraser simon.fra...@apple.comwrote: 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

Re: [webkit-dev] coding style and comments

2011-01-28 Thread Alexey Proskuryakov
28.01.2011, в 9:36, Peter Kasting написал(а): At the very least I agree with Simon's suggestion of class-level comments, especially w.r.t. ownership. I remember this comment http://trac.webkit.org/browser/trunk/WebCore/platform/PlatformString.h?rev=16622#L44 causing trouble. Here is some

Re: [webkit-dev] coding style and comments

2011-01-28 Thread Peter Kasting
On Fri, Jan 28, 2011 at 10:14 AM, Alexey Proskuryakov a...@webkit.org wrote: Do you have any specific mechanism in mind for keeping global comments accurate? No more than I have for keeping API usage or function implementations correct; that is, if we have comments, they must be as important

Re: [webkit-dev] coding style and comments

2011-01-28 Thread Maciej Stachowiak
On Jan 27, 2011, at 4:38 PM, Dirk Pranke wrote: I agree with all of the sentiments below, except for possibly one or two cases. Namely, sometimes you write code where the what is not obvious. In that situation, it may not be possible to change the code to make it more obvious, because

Re: [webkit-dev] coding style and comments

2011-01-27 Thread Eric Seidel
My personal preference (and I'd love to hear from other contributors) is that code should ideally be self-documenting. If I ever find myself writing a what does this do comment, I try to re-write the code to be easier to read. Normally that means breaking it into smaller pieces, and using static

Re: [webkit-dev] coding style and comments

2011-01-27 Thread Darin Adler
On the WebKit project we like “why” comments, but not “what” comments. Comments that say what the next block of code does usually are not a good idea. Instead by using appropriate names and granularity we want the code itself to say what the comment would have. We also frown on “textbook”

Re: [webkit-dev] coding style and comments

2011-01-27 Thread Ryosuke Niwa
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

Re: [webkit-dev] coding style and comments

2011-01-27 Thread Simon Fraser
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

Re: [webkit-dev] coding style and comments

2011-01-27 Thread Dirk Pranke
I agree with all of the sentiments below, except for possibly one or two cases. Namely, sometimes you write code where the what is not obvious. In that situation, it may not be possible to change the code to make it more obvious, because you are bound by contract. For example, suppose you are

Re: [webkit-dev] coding style and comments

2011-01-27 Thread Dirk Pranke
Two other ways to potentially answer these questions: 1) What are files that you all think *are* well commented? (pointing at files that aren't probably isn't that useful, and is certainly meaner ;). 2) One file over in that same directory, is a filesystem.py file that I wrote (most of). I think

Re: [webkit-dev] coding style and comments

2011-01-27 Thread Ryan Leavengood
On Thu, Jan 27, 2011 at 7:27 PM, Simon Fraser simon.fra...@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