First of all, I'd like to thank everyone who agreed with my view of automated unit tests as a perfectly good substitute of source code comments (of course, unit tests are much much more than a replacement for comments!). I also appreciate the folks who submitted constructive criticism and shared their personal rules of thumb for writing comments.
Some readers took offence on my use of terms like "cohesion", "coupling", and "cyclomatic complexity", calling them buzzwords. My friends, if these terms are just buzzwords to you, then you clearly are missing some important trends in our industry. If you are writing objects with hundreds of methods that pertain to dozens different responsibilities, or if your thousand-line functions have so many if-else statements it makes you dizzy, then no amount of source code comments will hide one simple fact: your code is bad and is in dire need of refactoring.
One often-repeated mistake was that I am advocating against ALL source code comments. This is simply not true, and if you read the blog post through the end, you will see a pretty funny example of a very legitimate comment one programmer left in his code.
Speaking of examples - I got a few posts saying they are "stupid", "straw-man", and not real. Well, I don't even know what to say... There are just two examples in my blog post, and both are taken verbatim from the StackOverflow discussion called "What is the best comment in source code you have ever discovered".
To all people who questioned my credibility, I am happy to say that I have been a professional programmer for over 16 years, used more programming languages than I care to remember, and was involved in the maintenance of large codebases. I do code reviews on a regular basis, and I always enjoyed respect of my colleagues. True, my current job title is no longer a "programmer", and I've been coding in C# exclusively for the last several years, but make no mistake - I am no "dabbler" when it comes to software development.
4 comments:
Hello Riyad. I was surprised today when the top entry on r/programming on reddit lead to your blog. Would never though that i stumble on you on the internet that way :)
I think most commenters took offense of your argument that because 90% of comments you encounter are useless, then commenting itself is a waste of time. It is akin of saying that if 80% of software projects fail then writing software is a waste of time.
You are arguing that a right architecture and good naming conventions should be enough to make any code clear and self evident. But in real life projects this is not the case. In reality programmer have to work with code (libraries) that are out of their control, and contain lots of bugs. Let me give you just one example. Delphi lets keyboard events fall through a popup message on its main form. So if you hit enter on a button, get a popup message, then hit enter again to press its OK button, the Enter key will fall back on a button on the form, causing it to trigger again and again and again. The only way to avoid it is to move the focus off to another control after responding to that event.
No matter how cleanly you designed your code. That grig.SetFocus; is a mystery to anyone who reads it. Unless you explain in comment why is it required to move off the focus.
Another case would be programming by convention, when programmer uses integers and strings to return success/error codes from a function. The type of the returned value does not convey any useful information. And if possible return values are not documented in comments, programmer who reads such code have to hunt down the meaning of it all over the place.
Instead of saying that writing comments is a waste of time, perhaps a better position would be to explain what is the role of comments in the code. Comments are there to explain why the code is written, not what it does.
The commenting examples you chose in your earlier posts were still strawman arguments. The "best" comments in that Stack Overflow page was the word "best" being used sarcastically. Those comments were exceptions, comments which were noteworthy precisely because they are uncommon. And most of those comments which were either jokes or were exceedingly bad (eg isAvailable()).
In your original post, you made a valid point that commenting *what* a piece of code does is worse than useless. But then you jumped to the conclusion that all comments are bad.
IMHO, commenting *why* a piece of code does what it does, as well as the author's *intention* is extremely helpful and a valuable tool with communicating with another programmer across space and time.
All will be fine and dandy with applications of design patterns and great constructs, but when you have to read someone's magic numbers and strings in code (especially those that deal with near mathematical constructs), you will be happy if there are some comments explaining intents or the algorithm, at least.
That said, comments and documentation of methods are two very different things. Documentation is necessary when it is going to be an API or is up for re-use and/or is extensible.
@Vagif: Good to hear from you! Thanks for sending your feedback. Of course, you are correct, and there are all sorts of legitimate reasons for leaving comments in the source code. What I was trying to say in my post is that we now have tools and techniques that allow us to transition from "thoroughly" to "sparingly" documented code. Unfortunately, the guy who submitted link to reddit didn't understand it and thought I was advocating against all source code comments. Sadly, he set the tone of the discussion and influenced a lot of derisive remarks.
Post a Comment