Take the 2-minute tour ×
Programmers Stack Exchange is a question and answer site for professional programmers interested in conceptual questions about software development. It's 100% free, no registration required.

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.

Do you know of any serious research regarding the efficiency of different commenting styles? 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?)
share|improve this question
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
add comment

closed as off-topic by gnat, Bart van Ingen Schenau, MichaelT, Robert Harvey, Dan Pichelman Dec 3 '13 at 0:04

This question appears to be off-topic. The users who voted to close gave this specific reason:

  • "Questions asking us to recommend a tool, library or favorite off-site resource are off-topic for Programmers as they tend to attract opinionated answers and spam. Instead, describe the problem and what has been done so far to solve it." – gnat, Bart van Ingen Schenau, MichaelT, Robert Harvey, Dan Pichelman
If this question can be reworded to fit the rules in the help center, please edit the question.

2 Answers

up vote 5 down vote accepted

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.

share|improve this answer
1  
Thanks, that is MOST helpful. –  Adam Matan Feb 24 '12 at 6:54
    
@AdamMatan please accept the answer if/when you decide it's the best. –  Yar Feb 24 '12 at 15:02
add comment

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.

share|improve this answer
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
2  
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
show 1 more comment

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