On Thu, Jul 12, 2012 at 2:03 PM, Ryosuke Niwa <rn...@webkit.org> wrote:
> On Thu, Jul 12, 2012 at 1:47 PM, Stephen Chenney <schen...@chromium.org>wrote: > >> On Thu, Jul 12, 2012 at 3:44 PM, Dirk Pranke <dpra...@chromium.org>wrote: >> >>> On Thu, Jul 12, 2012 at 10:53 AM, Ryosuke Niwa <rn...@webkit.org> wrote: >>> > On Thu, Jul 12, 2012 at 10:43 AM, Stephen Chenney < >>> schen...@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
_______________________________________________ webkit-dev mailing list webkit-dev@lists.webkit.org http://lists.webkit.org/mailman/listinfo/webkit-dev
