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?)
What has research shown about the effectiveness of comments?
comments
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. 