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

[Stephen Chenney]

On Thu, Jul 12, 2012 at 3:44 PM, Dirk Pranke <dpranke at chromium.org> wrote:

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

I should have been clearer. In this email thread there have been
guesstimates of the form:

Cost per year with poor commenting: t_understandWithoutComment *
n_engineersNeedingToUnderstand

Cost per year with good comments:  t_maintainComments * n_patches
+ t_understandWithComment * n_engineersNeedingToUnderstand

All costs are "per-code unit" and will likely vary depending on the code.
We are better off without comments if:

t_understandWithoutComment < t_maintainComments * n_patches / n_engineers
+ t_understandWithComment

We can argue about the appropriate values for t_* and n_*. The primary
observation is that the benefit of comments rises as more engineers need to
understand the code and patch levels (behavior changes) stay reasonably
constant. More behavioral changes argue for fewer comments.

We can all have fun fiddling the numbers to make our cases. Go for it in
the privacy of your own home.

For anything that looks like "core" code where lots of engineers need to
understand it, I think commenting wins most of the time. My current
favorite is "inDocument()". For peripheral code with frequent changes in
behavior, it's not worth it. There's a big grey area in between (like
Ryosuke's editing code) where the best approach is not obvious.

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
>

Absolutely. At heart this is a cultural issue and we could let it all play
out by pushing our individual opinions in patches and reviews. Over time
we'll see what happens.

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