On Wed, Jul 11, 2012 at 6:07 PM, Alec Flett <alecfl...@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.
_______________________________________________ webkit-dev mailing list webkit-dev@lists.webkit.org http://lists.webkit.org/mailman/listinfo/webkit-dev