7 August 2007
/* Comments Please */
Comments in code. Comments on checkins. Every programming language and source control tool supports comments. There must be thousands of articles on the web about how to do them properly, and as many more on how not to.
Every developer should already be using comments in their work. Descriptions on the algorithm chosen, what other algorithms were considered, usage notes for a custom class, a method's pre- and post-conditions, every single change that was made for a particular revision. If you are not already doing these, then this article is not for you. Neither is a career in software.
So why is poor/lack-of commenting still an issue in this millennium? Why don't your inline comments help me understand your code? Why can't I easily spot the revision you made a particular change? Why have you not written any comment at all?!!
Only high voltage electrodes can help answer that last one, but for the rest, the answer is why. Why is what's needed in comments. There is a lot of what in comments, but rarely a why. The what can often be induced by code inspection, but to make me induce the why is to ask me to read your mind. Whenever you are writing an inline comment or checkin comment, always ask yourself why did I do it this way, and a useful comment will result.
Implicitly, why also includes why not. Why were other approaches not taken? These are important too, as they will prevent another developer from replacing your carefully selected and beautifully crafted solution with something less appropriate you'd already deliberated over and ruled out.
Don't be surprised if you find it tough to write concise comments. It's basically summarising your entire thought process over the last hour/day/week into a few sentences. Don't be afraid to write a couple of short paragraphs if necessary. Comment well, and your co-workers will be grateful for it, and just maybe they won't form a plot on your life.
Every developer should already be using comments in their work. Descriptions on the algorithm chosen, what other algorithms were considered, usage notes for a custom class, a method's pre- and post-conditions, every single change that was made for a particular revision. If you are not already doing these, then this article is not for you. Neither is a career in software.
So why is poor/lack-of commenting still an issue in this millennium? Why don't your inline comments help me understand your code? Why can't I easily spot the revision you made a particular change? Why have you not written any comment at all?!!
Only high voltage electrodes can help answer that last one, but for the rest, the answer is why. Why is what's needed in comments. There is a lot of what in comments, but rarely a why. The what can often be induced by code inspection, but to make me induce the why is to ask me to read your mind. Whenever you are writing an inline comment or checkin comment, always ask yourself why did I do it this way, and a useful comment will result.
Implicitly, why also includes why not. Why were other approaches not taken? These are important too, as they will prevent another developer from replacing your carefully selected and beautifully crafted solution with something less appropriate you'd already deliberated over and ruled out.
Don't be surprised if you find it tough to write concise comments. It's basically summarising your entire thought process over the last hour/day/week into a few sentences. Don't be afraid to write a couple of short paragraphs if necessary. Comment well, and your co-workers will be grateful for it, and just maybe they won't form a plot on your life.
# posted by Mark @ 3:17 pm 
