6

I have been arguing with a friend about the necessity of comments, and the efficiency of different comment styles. The argument ended quite fast, as we could not find any research - or essay - that support either claim.

Has any serious research been conducted regarding the efficiency of different commenting styles? If so, what has it shown? I'm mainly interested with:

  • Length (I think that comments longer than a tweet are never read)
  • Type (I strongly favor comments that are actual code samples, explaining how to call a method)
  • Location (As a separate line? at the end of the line?)
  • 1
    I would question the funding priorities of any institution that supported "serious research" of this topic. :P – Dan J Feb 23 '12 at 18:11
  • Why have an example code as comment instead of as actual executable code? – CodesInChaos May 7 '14 at 13:56
8

The short answer is yes, there do exist published (in peer-reviewed journals and conferences) studies of various aspects of program comments.

Here are some examples:

Prechelt, et al (2001) determined that "Pattern Comment Lines" are effective when placed in programs in that maintenance tasks were completed faster with fewer errors.

Nurvitadhi, Wing Wah Leung and Cook (2003) determined that class comments are not useful for high-level understanding, however method comments helped with "low level program understanding".

A interesting read from the University of Montreal on comments in Java programs provides a good Related Work section that discusses some other research in this area.

None of these studies suggests that all comments in all situations are good. However they do provide some sound experimental evidence that comments are useful when done correctly.

5

There may be some research but I would take it with a large pinch of salt. Good comments are hard to define and very situational, its like asking for research on how good books are based on the length of the words or the number of pages.

Good comments are an art form.

On a side note I suggest you read code complete. Its a great guide for how to write good comments.

  • 2
    I'd also suggest reading Clean Code by Robert Martin – CaffGeek Feb 23 '12 at 17:24
  • I agree, a good book. – Tom Squires Feb 23 '12 at 17:30
  • 3
    This answer doesn't contain any wrong information as far as I can see, but it still is not an answer to the original question. – TehShrike Feb 23 '12 at 17:52
  • 2
    @TehShrike the answer is that there isn't any answer :) – Tom Squires Feb 23 '12 at 17:55
  • @TomSquires you don't need to post an answer to this question for people to get that point - an answer should contain research. If there are no answers, there is no research. – TehShrike Feb 23 '12 at 18:15

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service, privacy policy and cookie policy

Not the answer you're looking for? Browse other questions tagged or ask your own question.