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

Re: [webkit-dev] coding style and comments

2011-01-31 Thread Aaron Boodman
On Mon, Jan 31, 2011 at 7:18 PM, Peter Kasting 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 mailing list webkit-dev@li

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 som

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 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 multi

Re: [webkit-dev] coding style and comments

2011-01-31 Thread Peter Kasting
On Mon, Jan 31, 2011 at 12:47 PM, Maciej Stachowiak 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 actual lines

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 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".

Re: [webkit-dev] coding style and comments

2011-01-31 Thread Peter Kasting
On Sun, Jan 30, 2011 at 4:47 PM, Maciej Stachowiak 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 pretty

Re: [webkit-dev] coding style and comments

2011-01-31 Thread Konstantin Tokarev
31.01.2011, 03:41, "Ryan Leavengood" : > 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 k

Re: [webkit-dev] coding style and comments

2011-01-31 Thread Ryosuke Niwa
On Sun, Jan 30, 2011 at 4:41 PM, Ryan Leavengood wrote: > > 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. Can't agree m

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 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 t

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 Ryan Leavengood
On Sunday, January 30, 2011, Maciej Stachowiak 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 here is bette

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

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 Adam Barth
On Sun, Jan 30, 2011 at 7:40 AM, David Kilzer 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 many > comments w

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 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 b

Re: [webkit-dev] coding style and comments

2011-01-28 Thread Chris Marrin
On Jan 28, 2011, at 9:36 AM, Peter Kasting wrote: > On Thu, Jan 27, 2011 at 4:27 PM, Simon Fraser 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

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, bec

Re: [webkit-dev] coding style and comments

2011-01-28 Thread Peter Kasting
On Fri, Jan 28, 2011 at 10:14 AM, Alexey Proskuryakov 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 to reviewers a

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 causing trouble. Here is som

Re: [webkit-dev] coding style and comments

2011-01-28 Thread Peter Kasting
On Thu, Jan 27, 2011 at 4:27 PM, Simon Fraser 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 shouldn't be > messing wit

Re: [webkit-dev] coding style and comments

2011-01-27 Thread Ryan Leavengood
On Thu, Jan 27, 2011 at 7:27 PM, Simon Fraser 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 shouldn't be > messing w

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 thin

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 im

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 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

Re: [webkit-dev] coding style and comments

2011-01-27 Thread Ryosuke Niwa
On Thu, Jan 27, 2011 at 3:46 PM, Eric Seidel 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 readab

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” style

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 stati