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

[Stephen Chenney]

On Wed, Jul 11, 2012 at 6:07 PM, Alec Flett <alecflett at chromium.org> wrote:

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

The alternatives to comments are themselves subject to the "out-of-date"
problem to an even greater degree. Someone modifying or reviewing code with
comments nearby is far more likely to notice a problem with the comments
than they are to know that some blog post somewhere is now out of date due
to the code change. Even community knowledge is subject to out-of-date
problems, because most people don't look at most patches.

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

This is an excellent and compelling reason to have comments, and
documentation in general.  I cannot count the number of times I have
discovered problems with something at the time I was forced to write about
it. While Changelogs and bug reports are intended to enforce this level of
thinking, in most cases they are not as specific as I would expect comments
to be, particularly for medium to large patches.

Even if the comment is out of date, the time spent verifying that it is
incorrect is no different to the time one should spend verifying that a
change itself is correct.

Finally, arguing that something is bad because it might get out-of-date is
not particularly helpful. Much of the world's information goes out of date,
yet society still chooses to provide it. Everything from transit schedules
to online help pages. The anti-comment argument here is really that it is
not worth the effort of keeping the comments up to date. As several people
have shown, it is quite easy to come up with a formula that shows the cost
of maintaining comments is much lower than the cost of living without.

Cheers,
Stephen.
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.webkit.org/pipermail/webkit-dev/attachments/20120712/eb82aba6/attachment.html>