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!
Re: Projects being disrupted over issues about commenting...
I was a "code cop" once upon a time. I rejected a program during my tenure in QA (a C program) because there was a really obscure piece of code written in it that took me several minutes to figure out. I even asked my C programming colleagues to look at it before sending it back to the coder with a request for a comment. The turkey said "NO!". He said any competent C programmer should be able to figure it out. I said, "I figured it out, but it took me a while. Same thing with some other people who are competent C programmers." He still refused, and I refused to pass it to integration. After a meeting involving three levels of management, he relented. The comment was not great, but at least it was in his program. It only cost a few tens of thousands of dollars to get it in there.
So, if someone asks for a comment, put it in. There is always added value in comments if someone requests it.
Posted by Frank Moss on October 06, 2015 at 09:58 PM CEST #