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.
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
Hi all,
Have there been any threads or blog posts in the past over an
appropriate level of comments in the code? A brief search of the
Google and the list archives didn't really turn up anything.
From what I've seen, code in WebKit is much less commented than most
if not all large projects I've
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
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”
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
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
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
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
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
28 matches
Mail list logo