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?