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?)
Improve this question
2
  • 1
    I would question the funding priorities of any institution that supported "serious research" of this topic. :P
    – Dan J
    Feb 23, 2012 at 18:11
  • Why have an example code as comment instead of as actual executable code?
    – CodesInChaos
    May 7, 2014 at 13:56

2 Answers 2

Reset to default
9

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.

Improve this answer
0
4

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.

Improve this answer
6
  • 2
    I'd also suggest reading Clean Code by Robert Martin
    – CaffGeek
    Feb 23, 2012 at 17:24
  • I agree, a good book.
    – Tom Squires
    Feb 23, 2012 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, 2012 at 17:52
  • 2
    @TehShrike the answer is that there isn't any answer :)
    – Tom Squires
    Feb 23, 2012 at 17:55
  • 1
    @TehShrike this is, in fact, a comment, not an answer to the question. However, it does tow the party line (read Code Complete! Read Clean Code! Comments are art! yay!) so it gets upvoted and well received. I'm not saying that Tom is wrong, obviously, but -1 in order to promote serious discourse on programmers.
    – Dan Rosenstark
    Feb 23, 2012 at 22:35

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge that you have read and understand our privacy policy and code of conduct.

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