Commenting my code

A long time ago I wrote about how I felt about comments in my source code. It was back in 2010, but I'm not going to link back to those posts because I wrote them in Spanish. If you are sufficiently motivated, feel free to search the archives.

The story is that, back in the day, I wasn't very fond of comments. I had this personal quest where I had to refactor my code until every single comment was unnecessary. I still think is a noble mission, but the years have made me realize how hard it is to accomplish.

Add a few years of C development to the mix—where things are as hard to read as ancient hieroglyphs—, and my code has evolved to a completely different stage: nowadays half of my writing is not for computers to compile, but for humans to read and understand.

Time and experience do wonders to people.

There's something that hasn't changed, however: I never write comments about the what, but only about the why.

The what my code is doing should be obvious for any other developers — at least, I try hard. Sure, there are cryptic lines here and there, but most of the time, the code should be enough to the reader. The why however, is a different story: more often than not I try to go out of my way to make sure my intentions are clear through comments in the code, and every time I go back and read what I wrote, the ideas I had become apparent and I feel I'm right there the same day I came up with them.

I'm pretty much addicted to this, so I really think this is the last stage of the evolution regarding comments. I'll get better at writing them, for sure, but I don't think I can go back to noble missions that are hard to accomplish.

Have something to say about this post? Get in touch!

Want to read more? Visit the archive.