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
On Fri, Jul 6, 2012 at 7:59 PM, Ryosuke Niwa wrote:
> On Fri, Jul 6, 2012 at 4:54 PM, Per Bothner 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
On Fri, Jul 6, 2012 at 4:54 PM, Per Bothner 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 the implic
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 Jul 6, 2012 4:34 PM, "Maciej Stachowiak" wrote:
>
> On Jul 6, 2012, at 2:37 PM, Per Bothner 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 u
On Jul 6, 2012 4:29 PM, "Maciej Stachowiak" wrote:
>
>
> On Jul 6, 2012, at 2:18 PM, Ryosuke Niwa wrote:
>
>> On Fri, Jul 6, 2012 at 1:51 PM, Per Bothner wrote:
>>>
>>> Documenting what a function/method does is sometimes useful,
>>> but what is really important is documenting what (an instance
On Jul 6, 2012, at 2:37 PM, Per Bothner 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 separate from t
On Jul 6, 2012, at 2:18 PM, Ryosuke Niwa wrote:
> On Fri, Jul 6, 2012 at 1:51 PM, Per Bothner 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
On Jul 6, 2012 4:09 PM, "Benjamin Poulain" wrote:
>
> On Fri, Jul 6, 2012 at 3:49 PM, Ryosuke Niwa 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
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 inaccurate.
On Jul 6, 2012 3:04 PM, "Filip Pizlo" 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 other
ways of
On Fri, Jul 6, 2012 at 3:49 PM, Ryosuke Niwa 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 odd behavior
On Jul 6, 2012 3:16 PM, "Per Bothner" 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 of *their* ti
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 once
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 3:
On Jul 6, 2012 2:36 PM, "Per Bothner" 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 comments. In
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
per.
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 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. Yes
On Fri, Jul 6, 2012 at 2:26 PM, Joe Mason 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 c
> 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
On Fri, Jul 6, 2012 at 1:51 PM, Per Bothner 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 Fri, Jul 6, 2012 at
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 wrote:
> 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
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 wrote:
> The biggest annoyance I found is lack of class-level comments. For example
> what is an Interpreter? How many inst
[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 th
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 return
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 ne
On Fri, 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 retur
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 pointers which can never return 0, especially when
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 length
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
On Fri, Jul 6, 2012 at 11:42 AM, Dana Jansens wrote:
> On Fri, Jul 6, 2012 at 1:05 PM, 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 entr
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 changelo
On Fri, Jul 6, 2012 at 1:05 PM, 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 c
On Fri, Jul 6, 2012 at 11:34 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 valua
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 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 eac
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 us
38 matches
Mail list logo
