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

[Maciej Stachowiak]

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.

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. 

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.

Regards,
Maciej

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