The "B" Log

Ramblings About Programming

Comment Tags

Short blog posts are all the rage, right? I had some thoughts about tagging comments in code, so here they are.

Comments Usually Suck

Everyone knows the rule of thumb about comments. Well, maybe that's true. As undergrads, we were drilled with "comment your code!" incessantly. This led to loading up our code with slashes and useless monologue. Luckily, our assignments had due dates. This meant that comments never went out of date because we never looked at the code again.

Anyway, the rule of thumb is that comments should state why your code is doing something rather than what it is doing, but even the former can get you into trouble. The best approach is to "simply" write code that documents itself. Yeah... simple.

On to the Tags

"Comment tags" are something like // @refactor which are easily searched. I first saw this when watching Jon Blow work on his compiler, and it seemed like a neat trick for reminding yourself of later work. We all write code that we'll have to change later, but it needs to actually do something first. Comment tags can remind us to refactor, fix a bug, clean up code, or do a number of other things when we have time. The hidden benefit is that there is a searchable list of things that can be done when you don't really know what to do next or when you're not motivated to implement a new feature.

So far, I'm happy with this one neat trick.

You stay classy.

My major focus these days is to get better at programming. I use an email list to share stuff that I think is helpful. It keeps me focused on reading stuff that matters.