I’ve been reading about literate programming, and was reminded that most programmers don’t write comments in their code. Whether to write them or not is a question that’s asked all the time, in all circles – starting in school and all the way to teams of masters of the known universe like Linus (who I’m assuming is responsible for this).

In school I thought comments are good. I’ve seen a few people who felt the same change their mind once they started writing real software, and I was tempted to drop it myself, but I didn’t.

I’ve had the same arguments with myself that you’re thinking of now. Should I document design, exceptions, explain what complicated code does, go over the assumptions, etc.? This post is not about that, it’s about something I’ve realised a few days ago – a thought that may be slightly original.

Writing comments in my code makes me feel good. I’m not a design freek and my code goes through a couple of iterations before it’s even checked into version control, often followed by more restructuring when flaws are found. And then I write comments.

I look over a piece of code and think – what the hell is this doing, here? Oh – that’s to handle the weird case of an idiot unplugging the USB stick before it’s done. Comment. Man this function is long and hard to read. Several comments throughout telling a story (this being possible explains why it’s all in one function). Wow, at this moment I can actually grasp how the entire subsystem works – comments on top of the class and every function. Why is this a member variable and not a local one? Oh yeah, I remember – that’s bizarre but it works. Comment.

Did I manage to explain it? As I read my code I remember all the interesting, strange, unfortunate, and neat things I’ve done. And I write it down in plain english. I feel empowered when I can explain something that appears to be a terrible mess. I think this is why I still do write comments. And I know they’re useful because when I go back to my code a month later I can actually figure out what’s where using them.

Maybe it will work for you too?