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

[Stephen Chenney]

On Thu, Jul 12, 2012 at 5:31 PM, Maciej Stachowiak <mjs at apple.com> wrote:

>
> On Jul 12, 2012, at 1:47 PM, Stephen Chenney <schenney at chromium.org>
> wrote:
>
>
>
> 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.
>
>
> Surely we would expect the project's n_patches to scale approximately
> linearly with n_engineers. Or if not, I'm not super concerned about helping
> the engineers who are not contributing patches.
>

Not at all. Consider something like HashSet. Many many engineers need to
use and understand it, yet very few engineers will ever submit patches to
change it. The same holds, to a lesser extent, for something like
RenderElement or GraphicsContext, to name just two.

You've also failed to account for the cost of misleading comments, and the
> cost of comments that add no information value (like m_refCount++; //
> increase reference count by 1). These can  significantly hurt
> understandability. You may think my example of a low-information comment is
> a parody, but I've noticed that there is a high correlation between people
> who want to follow a policy of "lots of comments" and tendency to add
> comments almost exactly like that. If anyone doubts me, I can privately
> point you to some examples of comments in WebKit code that literally
> restate what the adjecent line of actual code does. I hate reading code
> like that, because it turns 1-page functions into 3-page functions.
>

I'd be happy to add a term to the cost function:

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

I don't doubt there are poor comments, both outdated and useless. That's a
reviewing failure. You have simply highlighted the fact that any standard
for comments requires reviewer attention. Hence "cost of maintaining
comments".

Thus, I'm much more interested in comments that pass the filter of people
> who prefer fewer comments and thus would spend their limited comment budget
> on ones that truly have value, than comments from people who believe in
> adding lots of comments. My Bayesian inference is that comments from the
> latter group have much lower average value per comment. When adding a
> comment, you should really think about whether the value outweighs the
> cost, just as when adding a line of actual functional code.
>

Yes. I don't think you'll find much disagreement. I don't believe anyone is
arguing for "lots of comments". The primary focus of this discussion, as I
recall reading, is: (1) class and member comments that describe system
behavior, (2) comments on invariants in code and (3) references to sections
of the spec that define behavior, and where we deviate.

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