Skip to content

Not commenting code is dangerous to your career

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”

  1. Your stellar (comment-free) code is deployed into production.
  2. The product manager changes the product definition and a new feature is born.
  3. One of your (“idiot”) co-workers makes a change (but not to your code).
  4. The tests pass and 2am this Friday, the code is to be deployed
  5. You go out drinking.
  6. Your (“idiot”) manager deploys the code to production and it breaks.
  7. Unfortunately, it breaks in your code.
  8. Your manager looks at your code and can’t figure out why you wrote the code a certain way.
  9. 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.

Posted in code review, management.

3 Responses

Stay in touch with the conversation, subscribe to the RSS feed for comments on this post.

  1. Dave Doolin says

    ah ah aha ah ah (this is me trying to catch my breath here…)

    Why some people think I can read and digest their turgid and convoluted code in a few moments when I have been spending all week trying to obtain money for their next contract is completely beyond me.

    The hilarious thing to me is that quite often when I do sit down and wade my way through someone’s code, I find it’s, frankly, not very good code after all.

    Haven’t met many coders willing to admit maybe their manager can’t read their code because… their code sucks!

Continuing the Discussion

  1. Just wondering…. » Blog Archive » Code Review #7 - Comment the “why” not the “what” linked to this post on March 4, 2009

    […] Just wondering…. « Not commenting code is dangerous to your career […]

  2. Just wondering…. » Blog Archive » Code Review #8: When to comment linked to this post on March 16, 2009

    […] last ? in a series of posts about commenting. See “the why”. See “not commenting is career threatening”. And the comment that started this […]

Some HTML is OK

or, reply to this post via trackback.