[webkit-dev] Comments in the code (Was Please include function-level comments in change log entries)

[Alec Flett]

I'm gonna chime in here, as I am 3 months into working on WebKit and the
lack of comments has driven me absolutely crazy.   This is a bit of a rant
from a self-declared newbie, but I'm trying to be constructive. I've
contributed to a handful of open and closed source projects. I am trying to
help, so bear with me. Maybe I'll feel differently in a year, but this is
how I feel today.

I've mostly been hacking on IndexedDB but also poking around other areas
just to try to learn how everything works. But as impressed as I have been
with the quality of the code itself in WebKit, the lack of comments have
made the learning curve very steep relative to anything else I've worked on
and frankly its nearly impossible to evaluate the quality of the
architecture because of the lack of comments. It's been like doing research
in a library where none of the books have tables of contents, indexes, or
bibliographies except for stacks of form-feed paper in some back room (i.e.
ChangeLogs). Sure, you can read each book page by page, but do you really
want to? ack/grep only gets you so far.

Ryosuke, you said earlier:

 To be fair, as I said, I was able to read WebKit code without much trouble
> 2-3 months into my internship. I'm not sympathetic to people who can't read
> code as well as an undergraduate college student.
>



This has been my experience as well, and in my mind this is not something
to be proud of. The learning curve on WebKit has been worse than probably
any other project I've worked on (and again it's not because the code is in
any way poor!) At some level I could say that it's made me interact with
other developers more in person/email/irc, but honestly that justification
feels like a cop-out. The only place I've seen this culture proliferate to
such a degree is in the RoR community, and .. well..

I've wasted way more time groveling through the same code over and over, or
bugging people when they have better things to do, trying to unpack why we
return early in this case but not in that other case, or how on earth an
object could end up in some particular state.

I absolutely do not buy that the "cost" of keeping comments up to date and
the "cost" of out-of-date comments outweighs the benefits - that has NEVER
been my experience and if anything the benefits of comments grow as the
number of people on a project grows. 20 minutes of your time
documenting/updating comments is worth 10 minutes of 10 (or 100)
developers' time *not* groveling through code. I also do not buy that all
code can be written in a self-documenting fashion. That's like saying that
nobody needs to write books about anything spec'ed by the W3C. Code is not
documentation no more than a spec is code.

If anything I'm a firm believer that taking the time to write a comment
forces you to write code correctly the first time. i.e. if I have to write
in a comment "this is true except in this one esoteric case" then it forces
me to reexamine that esoteric case and ask myself if that exception is
really necessary. In fact the way I generally write my code in WebKit is to
comment heavily so I can keep track of my own intentions, and then just
before sending off for review, strip all my code of comments, and that's
truly a waste.

I'm not saying that comments can't get stale but I implore everyone to ask
yourself: Have you actually encountered projects where a proliferation of
stale comments has a noticeably bad effect on productivity? Was there any
effort within the project community to improve the culture of keeping
comments up to date? Were significant regressions added due to stale
comments? How often did you encounter stale comments vs real, useful
comments?Alec


On Wed, Jul 11, 2012 at 10:58 AM, Ryosuke Niwa <rniwa at webkit.org> wrote:

> On Wed, Jul 11, 2012 at 10:44 AM, Adam Klein <adamk at chromium.org> wrote:
>
>> On Wed, Jul 11, 2012 at 9:51 AM, Ryosuke Niwa <rniwa at webkit.org> wrote:
>>
>>> On Wed, Jul 11, 2012 at 9:30 AM, Yaar Schnitman <yaar at chromium.org>
>>>  wrote:
>>>
>>> [(dev time of maintaining comments) + (risk of outdated comments causing
>>>> bugs X dev time of fixing resulting bugs)] << (dev time gained by more
>>>> contributors each being more knowledgable)
>>>>
>>>> No?
>>>>
>>>
>>> How did you reach such a conclusion? Do you have any data points to
>>> support that?
>>>
>>
>> Not sure about data points, but anecdotally I've noticed it's common
>> practice in WebKit to point newbies at particular contributors for
>> explanations of how things work (e.g., "oh, selection? that's tricky, ask
>> rniwa"). It seems plausible that some of the overhead of "oral tradition"
>> could be reduced by judicious application of comments (as well as other
>> written documentation, of course, like Dave Hyatt's blog posts and various
>> wiki pages).
>>
>
> As discussed on IRC, we can do that more appropriately on blog posts,
> technical articles, and wiki pages where we talk about the overall picture
> on how things fit/work together.
>
> Selection, for example, is a very complicated beast and even I don't fully
> understand all the details even though I've been almost exclusively working
> on editing and have touched the selection code on numerous occasions. To
> understand how selection works, one needs to understand several classes
> like FrameSelection, VisibleSelection, Position, VisiblePosition, and Range
> on top of a large amount of rendering code. For example, I've been working
> on this blog post about bidi text selection for the past 2-3 months and I'm
> not even half way done yet.
>
> On Wed, Jul 11, 2012 at 10:47 AM, Per Bothner <per.bothner at oracle.com>wrote:
>>
>> On 07/11/2012 09:51 AM, Ryosuke Niwa wrote:> On Wed, Jul 11, 2012 at 9:30
>> AM, Yaar Schnitman <yaar at chromium.org
>>
>>> How did you reach such a conclusion? Do you have any data points to
>>> support that?
>>>
>>
>> It seems plausible.  I doubt we have any data points to support the
>> opposite conclusion.
>
>
> I don't think anybody had claimed the opposite conclusion.
>
> Given that, I would suggest it is better for an
>> open-source project to err on the side of more public information
>> (i.e. openness) rather than less.
>
>
> Let us not start name calling.
>
> - Ryosuke
>
>
> _______________________________________________
> webkit-dev mailing list
> webkit-dev at lists.webkit.org
> http://lists.webkit.org/mailman/listinfo/webkit-dev
>
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.webkit.org/pipermail/webkit-dev/attachments/20120711/318594b7/attachment.html>