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

[Ryosuke Niwa]

On Thu, 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:
>

Thanks for the clarification. That makes a lot more sense.

Cost per year with poor commenting: t_understandWithoutComment *
> n_engineersNeedingToUnderstand
>
> Cost per year with good comments:  t_maintainComments * n_patches
> + t_understandWithComment * n_engineersNeedingToUnderstand
>

"poor" and "good" are not really useful distinction because we can all
agree that good comments are good. Also, we can't have all poor comments or
all good comments.

Thus, I postulate that the following formula will more likely depict the
world accurately:
Cost(engineer, numberOfComments) = timeToReadCodeWithoutComments(engineer,
numberOfComments) + timeToReadCodeWithComments(engineer, numberOfComments)
+ timeToMaintainComments(engineer, numberOfComments) +
timeWastedOnWrongComments(engineer, numberOfComments)

Cost(engineers, numberOfComments) = sum of cost(engineer, numberOfComments)
over engineers.

Even in this model, there is a gross simplification that only the number of
comments, not quality or the length of each comment, matters. We need some
experiments to see whether such a simplification can be acceptable or not.
Now, let us further assume that all engineers are equal, or that we can
someone determine the "average" engineer among us (pending another
experiment here). So the above formula reduces to:

Cost'(numberOfComments) = numberOfEngineers ×
(timeToReadCodeWithoutComments(engineer, numberOfComments) +
timeToReadCodeWithComments(engineer, numberOfComments)
+ timeToMaintainComments(engineer, numberOfComments) +
timeWastedOnWrongComments(engineer, numberOfComments))

And the optimization problem we're solving is the minimization
of Cost'(numberOfComments) over numberOfComments.

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