Questions About Commenting 📎
Cody asked me the following questions about code quality and commenting for a research paper:
Cody: What is a good, necessary comment?
Adam Bien: A comment should be brief and explain the developer's intentions or the "why?". A reader wrote a really concise advice how to write JavaDoc. Java documentation is a very good example how to write good documentation.
Cody: What is a bad comment and how much could it cost?
Adam Bien: Outdated comments are the worst. Usually comments are auto-generated by the IDEs and so entirely superfluous. Auto-generated comments are completely ignored by developers and so cannot cause any harm.
Cody: Can you describe any experiences where a project was disrupted over an issue involving code comments?
Adam Bien: Projects are disrupted by QA departments forcing developers to comment all public methods. In such cases developers are forced to waste their time for comments without any added value.
Cody: While troubleshooting or maintaining software, to what extent can good comments help the process?
Adam Bien: In all troubleshooting projects so far we only relied on the debugger and the source code. In problem-solving task forces I neither trust comments nor logs. However a pointer in a comment to an algorithm or a usage example can be really helpful.
If you could have the perfect developer to work alongside, what would he or she be like?
Interested in programming with a good sense of humor. Programming should be fun.
Comments are extracted for documentation as well. In general, how could software documentation be improved?
Documentation should be as brief as only possible. Ideally the code should be self-documenting. Also a good, explorative UI, only requires a minimum set of documentation.
Do you think it would be possible to scientifically measure comments to determine if they are good or bad, or is it just a matter of preference?
It is also hard to scientifically measure the quality of a novel. It should be possible to measure the amount of redundancy of a comment comparing it with the corresponding code snippet. I think we could scientifically proof that a comment is bad, but is really hard to scientifically approve the quality of a comment.
Cody -- thank you for the questions and good luck with your work!