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 am an advocate of commenting on source code and documenting software products. It is my personal experience and observation that working on source code that is rigorously commented has helped me in different ways when I have had to grow software or maintain it.

However there's another camp that says commenting is ultimately worthless or its value is questionable. Numerous proponents of coding without commenting argue that:

  • If a piece of code is well-written, it is self explanatory and hence does not need commenting
  • If a piece of code is not self-explanatory, then refactor it and make it self-explanatory so that it does not need any comments
  • Your test suite is your live documentation
  • Over time code and comments get out of sync and it becomes another source of headaches
  • Agile says working code is more important than piles of documentation, so we can safely ignore writing comments

To me this is just dogma. Again, my personal observation has been that software written by teams of smart and experienced developers ultimately end up with a considerable amount of code that is not self-explanatory.

Again, the Java API, Cocoa API, Android API, etc. show that if you want to write and maintain quality documentation, it is possible.

Having said all these, conversations about pros and cons of documentation and commenting on source code that are based on personal beliefs usually do not end well and lead to no satisfying conclusions.

As such I am looking for academic papers and empirical studies about the effects of software documentation, especially commenting source code, on its quality and maintainability as well as its effects on team productivity.

Have you stumbled upon such articles and what's been the outcome of them, if any?

share|improve this question

closed as off-topic by gnat, MichaelT, GlenH7, Michael Kohne, amon Jan 2 at 8:00

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, MichaelT, GlenH7, Michael Kohne, amon
If this question can be reworded to fit the rules in the help center, please edit the question.

2  
I think this is an interesting question anyway, but I am not much surprised that it might get closed here. That's why I've posted this on Quora as well. –  Behrang Feb 20 '13 at 14:27
4  
@gnat - It seems to me that "What research has been done in this aspect of the field of software development?" is a rather different question than the "please give me books on a subject" requests that are not quite welcome. –  Josh Kelley Feb 20 '13 at 14:45
1  
Just from reading title : There are no empirical studies about effects of anything on quality. If there were, this site wouldn't exist. –  Euphoric Feb 20 '13 at 14:56
2  
@Euphoric your two statements contradict each other. If we ignore the "crazy" 30 year old document, there is no conflict. But anyway, we should not ignore findings just because they're old, but critically appraise how they relate to modern work (as we should with new results too). –  user4051 Feb 20 '13 at 15:44
3  
@Euphoric I wish you'd post that as an answer, so I could downvote your total lack of research in your blanket assertion. There are tons of papers and research, empirical and otherwise, about the effects of different techniques on software quality. Have you studied anything about Software Engineering? –  Andres F. Feb 20 '13 at 16:08

1 Answer 1

In "The effect of modularization and comments on program comprehension" (1981), Woodfield, Dunsmore, and Shen found that "subjects whose programs contained comments were able to answer more questions than those without comments."

However, in "Learning a Metric for Code Readability" (2010), Raymond P.L. Buse and Westley Weimer found that comments have only a limited effect on readability and quality:

From the abstract:

We construct an automated readability measure and... show that this metric correlates strongly with three measures of software quality: code changes, automated defect reports, and defect log messages... Our data suggests that comments, in of themselves, are less important than simple blank lines to local judgments of readability.

From page 12:

We found that comments were are only moderately well-correlated with our annotators’ notion of readability (33% relative power). One conclusion may be that while comments can enhance readability, they are typically used in code segments that started out less readable: the comment and the unreadable code effectively balance out. The net effect would appear to be that comments are not always, in and of themselves, indicative of high or low readability.

Keep in mind that the "coding without commenting" proponents aren't saying that code without comments is better than code with comments. They're arguing that a particular style of code without comments - one that extracts code into methods with self-describing names, one that introduces explaining variables, one that has a good test suite - is better than code that doesn't do those things but does have comments. This could complicate the applicability of any studies that have been done.

share|improve this answer
1  
The Woodfield et al paper is about a particular variety of comments, roughly equivalent to what would now be called Javadoc: "Specifically, this research attempts to determine if short comments, inserted just before a logical module, can aid comprehension by briefly describing the function of the logical module and helping to define the logical module's boundaries." –  user4051 Feb 20 '13 at 17:59
    
I should have added at the time: that's not to say it doesn't have value, indeed it's an interesting and well-constructed study. I just thought it needed saying that they're not taking about all comments. –  user4051 Feb 20 '13 at 19:51

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