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

[Ryosuke Niwa]

On Thu, Jul 12, 2012 at 2:03 PM, Ryosuke Niwa <rniwa at webkit.org> wrote:

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

where engineer here is the "average" engineer.

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