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

[Dirk Pranke]

On Thu, Jul 12, 2012 at 10:53 AM, Ryosuke Niwa <rniwa at webkit.org> wrote:
> On Thu, Jul 12, 2012 at 10:43 AM, Stephen Chenney <schenney at chromium.org>
> wrote:
>>
>> 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.
>
>
> I object to that conclusion. I've never seen any scientifically sound data
> posted on this thread either for or against having comments. Furthermore,
> just because we can come up with a formula doesn't mean that the formula
> models the nature of the world well.

This is certainly true. I doubt you will see such a study, because
it's very culturally-specific (in the sense that every group working
on a shared code base is a culture).

All code reading is training; you have to learn the styles and idioms
of the codebase.

As an aside, in WebKit, I think the culture is actually actually
anti-comment enough that it's trained some people to not read comments
at all, and so the value of comments is even lower. I have often had
people ask questions about code in reviews that were answered by
comments right above the lines in question :).

-- Dirk