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: 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. We can all have fun fiddling the numbers to make our cases. Go for it in the privacy of your own home. For anything that looks like "core" code where lots of engineers need to understand it, I think commenting wins most of the time. My current favorite is "inDocument()". For peripheral code with frequent changes in behavior, it's not worth it. There's a big grey area in between (like Ryosuke's editing code) where the best approach is not obvious. As an aside, in WebKit, I think the culture is actually actually > anti-comment enough that it's trained some people to not read comments > at all, and so the value of comments is even lower. I have often had > people ask questions about code in reviews that were answered by > comments right above the lines in question :). > > -- Dirk > Absolutely. At heart this is a cultural issue and we could let it all play out by pushing our individual opinions in patches and reviews. Over time we'll see what happens. Cheers, Stephen.
_______________________________________________ webkit-dev mailing list webkit-dev@lists.webkit.org http://lists.webkit.org/mailman/listinfo/webkit-dev