There is this myth that code can be self-documenting and that comments are not necessary in good code. Michael recently comment on an earlier blog post advocating the idea of self-documenting code.
“Self-documenting” code is a career-damaging concept, because:
- Your “manager” (person who decides you stay employed) is an “idiot”,
- Your co-workers are “idiots”,
- You are an “idiot”
- The product manager is an “idiot”
- Your client is an “idiot”
Your “manager” (person who decides you stay employed) is an “idiot”
That’s me. The guy who has 6+ people to manage has to figure out business plans and a much of non-technical stuff that has no doubt resulted in permanent brain damage.
Your manager is code reviewing all the changes by his direct reports. A task that takes a few minutes every day… unless there are no comments. I know that your manager should be able to immediately see what the code does. But remember your manager is an “idiot”. Unfortunately for you, he signs your paycheck.
Also unfortunately for you, if your manager doesn’t immediately understand your change — you are an “idiot” in his eyes.
You have also just turned a 15-minute task into a 2-hour task. He didn’t really want to be home with his family.
Your co-workers are idiots
Lets agree, your code was stellar but then your co-workers came in and mucked it up. They did a stupid refactoring and broke everything.
The code was “obvious” but not to them.
You are an idiot
Your manager returns from a two-week vacation and is code reviewing 2 weeks of changes. Your manager is asking about a “odd” change that you did 14 days ago.
- Can you explain it clearly?
- Do you remember your thinking at the time?
- Alternative solutions that you tried and failed?
The product manager is an “idiot”
- Your stellar (comment-free) code is deployed into production.
- The product manager changes the product definition and a new feature is born.
- One of your (“idiot”) co-workers makes a change (but not to your code).
- The tests pass and 2am this Friday, the code is to be deployed
- You go out drinking.
- Your (“idiot”) manager deploys the code to production and it breaks.
- Unfortunately, it breaks in your code.
- Your manager looks at your code and can’t figure out why you wrote the code a certain way.
- Its 3am now. He calls you up. Are you going to remember why and are you going to be able to help him?
Lets pretend that the test coverage is better and the problem is discovered before deployment. But your change was made 3 months ago, are you going to be able to explain the thought process for the change?
Your client is an “idiot”
You are independent and you take on clients. Your new client is a non-technical person who needs your awesome coding skills. Now you are in trouble. A non-technical product manager and a non-technical manager (they are paying you!).
But your code is self-documenting right?
Not to them. The product is late. The doubts grow in their head. They ask a friend to look at your code. Their friend (“another idiot!”) says the code looks like garbage and he cannot tell why you wrote the code a certain way. The client starts to push back on paying your invoices. Things get ugly.