Developers: Proceed with caution before commenting your code
- select the contributor at the end of the page -
The comment conundrum
About a decade ago I was in charge of a large project in .NET 1.0. There were almost as many bugs in the .NET Framework that hit us as in our custom code, and to make matters worse we weren't familiar with the .NET Framework at the time. It was a sticky situation, to say the least. But here's the real kicker: All methods, fields and property getters and setters (including private ones) were all zealously commented.
Part of my job was playing Comment Police Officer, making sure that developers were following the guidelines for comments. Not surprisingly, I had other duties that weren't receiving my full attention. Thankfully, the project was a success (it's still in production today). But the reality of the situation is that those never-ending code comments didn't factor into our win. I know this because I spent many late nights coding without ever reading comments; a surefire indicator that we would have been just fine (and would've gotten home a heck of a lot earlier in those tense weeks) if we hadn't spent so much additional time writing these comments.
That extra time didn't do us any favors, which became even more clear when I received a call from the client, informing me that if we weren't up and running over the next few days, the project would be off. All at once, I realized the burden of having accumulated thousands of lines of comments; it was almost as if one single developer was constantly dedicated to writing plain text. And, let's not forget that those comments were almost never used in development. It's safe to assume that they never affected any design decision, at least not any that could be noticed in the end product. Even the documentation that was produced from comments was largely ignored,not to mention that only a small fraction of comments really went through the filters all the way to the final documents.
The risk in routine
As time passed, the more projects I took on (some with company-wide standards for writing comments in code), the more I began to notice the stupidity of forced comments. It might sound silly, but daily routine can be a dangerous thing.
Think about it like this: A developer gets used to writing meaningless comments, to the point that he's no longer really thinking it through. Take the GUID field, for example. It gets the usual, meaningless comment “GUID.” This blind tactic of commenting every word of code causes the developer to lower his guard, and he can no longer make the distinction between an important case of GUID and an everyday event of the width field. Months later somebody starts to send that GUID as a token over the network. This could have been avoided (and the company wouldn't have had to close the operation after an elaborate hacker attack) if the comment instead said, “Cryptographically insecure GUID.”
Know when to comment
Eventually, I began avoiding writing comments altogether. Being involved with smaller projects allowed me to measure the impact of comments versus no comments. As you've probably gathered by now, I found that there was no impact when comments were avoided. Sometimes this meant a few thousand lines of code without a single line of comment, and other times it meant one line of comment in just two or three places.
In the instances where there were just a few comments, these ended up being worth more than the thousands that were forced. The few that existed were meaningful, and served a greater purpose than simply following protocol. Not only that, but it prompted me to actually read the comments that were there, because at this point I knew they deserved my attention.
It's also worth noting that it's easier to work with code when there are no sections of text and XML mixed in. It's simpler yet to write custom documentation by hand without relying on the automated conversion tools.
Bottom line? It's possible to write code without comments, as long as you know when and where they're actually needed.
