Comment your damn code

I’m just going to come right out and say it:

Comment your damn code.


Every now and then I run into an engineer–sometimes pretty high level–who thinks that you don’t need to comment code. I’m going to call bullshit on this. I’ve been doing this a long time. Chances are, way longer than you. We are right in the middle of coding our asses off trying to launch something awesome, yet we still comment practically everything. There’s no excuse not to. Every 3 to 7 lines of code you’ll find some amount of editorializing. Maybe every few hundred lines you’ll find a good joke too.


Where the errors are

Look, there is what you intend and what you write. Your bugs are in between the two. When you write comments you are telling me what you meant to do. You code is telling me what you did. Either the flaw is in what you intended to do or, if your intent was correct, then it’s in your code. Help me know which is which.

Don’t be lazy

A common argument that I hear is that comments will get out of date because code will be updated but comments won’t be. Are you not updating comments? Your coworkers? Stop being lazy and stop settling for a culture where it’s okay to be lazy. Communicate how you work and let other people know that you’d like the same courtesy. Not commenting because someone, somewhere, in the future might do you wrong is just looking for excuses.

You’re a Journeyman

Gender neutral of course, but you’re a Journeyman. As such you have an obligation to teach others that are still learning. Your comments coach the Youngling who is reading your code. Tell them why you choose to use a Tuple in this case, but not the other (bonus points for links to stack overflow or dotnetperls … you know you can do that in your comments, right?) What are you taking a shortcut here? If you’re not taking shortcuts, then you’re not shipping so you better tell the Youngling what was special about this case. Otherwise you’ll end up with all of the wrong copy and pasted code everywhere. Look! Now your crappy code is a company pattern! No comments and all!

You can type

Part of my hiring process is whiteboard coding and keyboard coding. All good coders are touch typists. So you type 40 – 60 wpm. So then tell me again why aren’t you writing comments while you blaze through your code? Because clearly the 30 seconds that you take now to tell me about what is going on in this icky mess that the biz dev guy had to have done this week to get a nice $75k this month needs to ship. But what are we going to do next month. Can we rip it out? Or is this code locked in stone. I know what the code says. But tell me the intent.

You’re going to get old

I told you. I’ve been doing this for a while, probably before you entered middle school. I’m still slinging code and I still love it. And one day you’ll be old like me too. And if you’re like me (and I’m not an intellectual slouch mind you) the day will come when you know too many layers, too many abstractions, too many stacks that you can’t remember it all, all of the time. Your code comments will guide you. They’ll remind you that six months ago you did things this way, with this pattern and that it was pure awesomesause. And if you’re really good–and still evolving as a coder–you’ll realize that this code was crap and now you’d do it a completely different way. But you’d still have your comments to remind your own damn self what you were thinking and why. And you won’t be so much as old as experienced, growing, and knowing where you were six months ago before you knew any better.

So comment your damn code.

An article by James Bright