It appears that lately most WebCore change log entires don’t include any
comments on individual functions. An overall description of the change at the
top of the change log entry is valuable, but it is no substitute for describing
the changes to each function. Good function-level comments are
On 07/06/2012 10:05 AM, Dan Bernstein wrote:
It appears that lately most WebCore change log entires don’t include any
comments on individual functions. An overall description of the change at the
top of the change log entry is valuable, but it is no substitute for describing
the changes to
On Friday, July 06, 2012 11:34:01 AM Per Bothner wrote:
On 07/06/2012 10:05 AM, Dan Bernstein wrote:
It appears that lately most WebCore change log entires donât include any
comments on individual functions. An overall description of the change at
the top of the change log entry is
On Fri, Jul 6, 2012 at 11:34 AM, Per Bothner per.both...@oracle.com wrote:
On 07/06/2012 10:05 AM, Dan Bernstein wrote:
It appears that lately most WebCore change log entires don’t include any
comments on individual functions. An overall description of the change at
the top of the change log
On Fri, Jul 6, 2012 at 1:05 PM, Dan Bernstein m...@apple.com wrote:
It appears that lately most WebCore change log entires don’t include any
comments on individual functions. An overall description of the change at
the top of the change log entry is valuable, but it is no substitute for
I find that the function level comments, while potentially more time consuming
to create are more beneficial than the comments at the top. It makes it not
only easier to review but for also when going through the history and trying to
see what changes were made.
About iterations of the
On Fri, Jul 6, 2012 at 11:42 AM, Dana Jansens dan...@chromium.org wrote:
On Fri, Jul 6, 2012 at 1:05 PM, Dan Bernstein m...@apple.com wrote:
It appears that lately most WebCore change log entires don’t include any
comments on individual functions. An overall description of the change at
the
On 07/06/2012 11:41 AM, Ryosuke Niwa wrote:
Indeed, we try to avoid adding comments as much as possible since
comments tend to get out-of-date very quickly, we don't want to be
spending all our time updating comments.
Heavens forbid that someone who actually understands the code should have
to
Per:
You began by thread-jacking Dan's discussion of ChangeLogs, and now
appear to be attacking a seasoned contributors polite response with
sarcasm and derision.
I recommend you soften your words, and try again on another thread.
Commenting, or lack there of, has been discussed at great
On Fri, Jul 6, 2012 at 1:35 PM, Joe Mason jma...@rim.com wrote:
As has been noted in a recent thread, WebKit strives to make the code
clear and understandable rather than have embedded comments that can become
obsolete. One common practice that I find quite opaque is for classes to
have
On Jul 6, 2012, at 1:35 PM, Joe Mason wrote:
As has been noted in a recent thread, WebKit strives to make the code clear
and understandable rather than have embedded comments that can become
obsolete. One common practice that I find quite opaque is for classes to
have functions returning
On 07/06/2012 01:02 PM, Eric Seidel wrote:
You began by thread-jacking Dan's discussion of ChangeLogs, and now
appear to be attacking a seasoned contributors polite response with
sarcasm and derision.
Sorry - it wasn't meant to be a thread-jacking, but the issue of
commenting in WebKit hit a
[For the record, in an appropriate thread. No need to respond
if you feel this has been adequately discussed in the past.
I'm happy to let the thread die.]
The biggest WebKit annoyance I have is lack of class-level comments.
For example what is an Interpreter? How many instances are there in
Starting a new thread, since this has wandered a fair bit off topic (and Eric
had a good point that it's kind of a threadjack).
On Jul 6, 2012, at 12:54 PM, Per Bothner per.both...@oracle.com wrote:
The biggest annoyance I found is lack of class-level comments. For example
what is an
As Eric pointed out, this is completely off the topic of the thread now. So
moving to a new thread.
On Fri, Jul 6, 2012 at 12:54 PM, Per Bothner per.both...@oracle.com wrote:
On 07/06/2012 11:41 AM, Ryosuke Niwa wrote:
Indeed, we try to avoid adding comments as much as possible since
On Fri, Jul 6, 2012 at 1:51 PM, Per Bothner per.both...@oracle.com wrote:
Documenting what a function/method does is sometimes useful,
but what is really important is documenting what (an instance of)
a class *is* and (preferably) how it relates to other objects.
For some classes, yes.
On
From: Filip Pizlo [fpi...@apple.com]
Sent: Friday, July 06, 2012 4:52 PM
To: Joe Mason
Cc: WebKit Development [webkit-dev@lists.webkit.org]
Subject: Re: [webkit-dev] Pointers and self-documenting code
It's not at all clear that this is correct.
Is it correct for the font size to be
On Fri, Jul 6, 2012 at 2:26 PM, Joe Mason jma...@rim.com wrote:
From: Filip Pizlo [fpi...@apple.com]
Sent: Friday, July 06, 2012 4:52 PM
To: Joe Mason
Cc: WebKit Development [webkit-dev@lists.webkit.org]
Subject: Re: [webkit-dev] Pointers and self-documenting code
It's not at all
On 07/06/2012 02:18 PM, Ryosuke Niwa wrote:
I'd argue that we should still strive to make class names
self-explanatory as much as possible, and use comments as the last resort.
Fair enough. However, it's hard to come up with reasonably short and
readable
names that are self-explanatory.
On 07/06/2012 02:02 PM, Maciej Stachowiak wrote:
[... reasonable stuff I fully agree with - but one question ...]
Documenting ownership and lifetime relationships is also useful. We have tended
to do that as diagrams separate from the code, since the places where it is
most needed tend to be
On 07/06/2012 01:51 PM, Per Bothner wrote:
[For the record, in an appropriate thread. No need to respond
if you feel this has been adequately discussed in the past.
I'm happy to let the thread die.]
Let's ignore this thread - we already have 2 other new treads ...
--
--Per Bothner
On Jul 6, 2012 2:36 PM, Per Bothner per.both...@oracle.com wrote:
On 07/06/2012 02:18 PM, Ryosuke Niwa wrote:
I've found that our culture of not adding comments have given me a
pressure to think really hard to come up with better class names rather
than going with vague names with explanatory
It is indeed a problem of incentives.
Nobody has the incentive to maintain a class comment when making changes, since
comments are not checked by the compiler.
Therefore, it's much better to not write comments, and instead find other ways
of making the code legible.
-F
On Jul 6, 2012, at
On 07/06/2012 02:02 PM, Ryosuke Niwa wrote:
As Eric pointed out, this is completely off the topic of the thread now.
So moving to a new thread.
[Alas we now have 3 new treads ...]
Heavens forbid that someone who actually understands the code should
have
to update the comments
On Jul 6, 2012 3:16 PM, Per Bothner per.both...@oracle.com wrote:
On 07/06/2012 02:02 PM, Ryosuke Niwa wrote:
Heavens forbid that someone who actually understands the code should
have
to update the comments once in a while. Better to keep it
inscrutable
so newbies spend all
On Fri, Jul 6, 2012 at 3:49 PM, Ryosuke Niwa rn...@webkit.org wrote:
It DOES. Even today, I find many comments (even FIXMEs) that are
out-of-date. Say you add a some comment to a function A because of some odd
behavior of another function B, which A calls. Someone awesome later gets
rid of the
On Jul 6, 2012 3:04 PM, Filip Pizlo fpi...@apple.com wrote:
It is indeed a problem of incentives.
Nobody has the incentive to maintain a class comment when making changes,
since comments are not checked by the compiler.
Therefore, it's much better to not write comments, and instead find
At least for JavaScriptCore, I think that this is not a solvable problem. I
suspect there are other parts of the code where this is true. There are many
central classes that have such subtle behavior, which changes so often, that:
- If you had a comment then it would be perpetually
On Jul 6, 2012 4:09 PM, Benjamin Poulain benja...@webkit.org wrote:
On Fri, Jul 6, 2012 at 3:49 PM, Ryosuke Niwa rn...@webkit.org wrote:
It DOES. Even today, I find many comments (even FIXMEs) that are
out-of-date. Say you add a some comment to a function A because of some
odd
behavior of
On Jul 6, 2012, at 2:37 PM, Per Bothner per.both...@oracle.com wrote:
On 07/06/2012 02:02 PM, Maciej Stachowiak wrote:
[... reasonable stuff I fully agree with - but one question ...]
Documenting ownership and lifetime relationships is also useful. We have
tended to do that as diagrams
On Jul 6, 2012 4:29 PM, Maciej Stachowiak m...@apple.com wrote:
On Jul 6, 2012, at 2:18 PM, Ryosuke Niwa rn...@webkit.org wrote:
On Fri, Jul 6, 2012 at 1:51 PM, Per Bothner per.both...@oracle.com
wrote:
Documenting what a function/method does is sometimes useful,
but what is really
On Jul 6, 2012 4:34 PM, Maciej Stachowiak m...@apple.com wrote:
On Jul 6, 2012, at 2:37 PM, Per Bothner per.both...@oracle.com wrote:
On 07/06/2012 02:02 PM, Maciej Stachowiak wrote:
[... reasonable stuff I fully agree with - but one question ...]
Documenting ownership and lifetime
On 07/06/2012 03:49 PM, Ryosuke Niwa wrote:
If nothing else
it's a useful sanity check: If something changes enough that you need to
change a comment, that suggests it's a good thing to take the time to
think through the implications well enough to write them down.
We do that in change logs.
On Fri, Jul 6, 2012 at 4:54 PM, Per Bothner per.both...@oracle.com wrote:
On 07/06/2012 03:49 PM, Ryosuke Niwa wrote:
If nothing else
it's a useful sanity check: If something changes enough that you need to
change a comment, that suggests it's a good thing to take the time to
think through
On Fri, Jul 6, 2012 at 7:59 PM, Ryosuke Niwa rn...@webkit.org wrote:
On Fri, Jul 6, 2012 at 4:54 PM, Per Bothner per.both...@oracle.comwrote:
On 07/06/2012 03:49 PM, Ryosuke Niwa wrote:
If nothing else
it's a useful sanity check: If something changes enough that you need to
change a
On 07/06/2012 08:23 PM, Ryosuke Niwa wrote:
Again: Differing cultures
Indeed. You just need to get used to it.
The reasonable man adapts himself to the world; the unreasonable one
persists in trying to adapt the world to himself. Therefore, all
progress depends on the unreasonable
36 matches
Mail list logo
