// comments considered harmful

There’s an interesting paradox in teaching programming.  We (and by we I mean ‘they’) love to teach our students to use comments in code.  We (’they’) deduct marks if they are missing, return work that isn’t fully commented, etc.  But!  I’m going to go on record as saying that comments are evil.  The reason that students are told that comments are good and have no down side is because 99.999% of programming done by students involves code that will never never have to be maintained.  I only teach using old, large code that we have to maintain and evolve.  And in the context of evolving code vs. the one-off, you don’t want to see a lot of comments.

My in-laws just replaced a really beautiful wooden railing around their porch with one made of aluminum.  Despite ten years of painting and repainting, the wood had rotted.  Comments are evil because, like the wood trim you loved when you originally built the house, they have to be carefully maintained separate from the things they surround.

I was just talking with a student on irc about a piece of code he’s porting.  He was stuck on the right answer because he had decided to read the comments instead of the code itself.  If you ignore the comments and just read the code, you get most of the way there.  If you then read the tests that go with the code, you get the rest of the way: code + tests > code + comments.  Reading code is hard.  Reading comments only seems easier until you realize that they are wrong.

So far I’ve been talking about well meaning comments, the kind that are meant to shed light on a tricky algorithm to follow.  These are written at the time of the first commit, and then as the code evolves, they drift out of sync.  But what’s even worse are bits of code that are left commented-out and stay in the code!  No one is brave enough to delete them (note: this is what version control is for), and everyone carefully dances around them in case they need to be re-awoken some day.

The problem with comments is that they are deemed sacred.  They seem to come from a person instead of a machine.  When I look at code, it’s all of a kind: the syntax and vocabulary is that of the computer, and you can safely rewrite it without fear.  But comments seem to come with some sort of deep sincerity.  They whisper things long forgotten, like a faded photograph that falls from between the pages of a book.  Who are these people?  Where were they when this was taken?  Why is it in here?

The way to use comments is to do so sparingly, and to put your efforts into tests instead of prose.  Don’t get me wrong, I want to read your prose piece; just not before I try to understand your function.