Chaos Program

In my current employment I’m a website programmer. And a technology researcher and system administrator and probably a couple other things. But that’s not important right now. It’s the programming stuff that matters tonight. I have a big deadline coming up in a couple days and I’ve been putting in some extra hours and I’ve had something of an epiphany. It’s probably nothing new to other programmers but it is to me.

We need more comment labels.

It’s like this: Programmer’s make notes in the code we write. They’re called comments. There are certain commonly accepted prefixes that can start a comment – so commonly accepted that certain IDEs (for people who don’t know what that means, think of it as a window you type programs into) recognize them. Some IDEs will apply special highlighting to the labels so they are easy to see. This makes it simple to look at a file and find places where improvements need to be made.

The most common of these labels are TODO and FIXME. Here’s an example from one of my current projects:

#TODO: Move this function to the observer

For the record, I use TODO  a lot more often than FIXME. It would be nice to never use FIXME but sometimes there are other considerations than making every piece of code perfect. Like lunch. Or the demo that’s coming up in 15 minutes and the code had better be working (even if it’s not very pretty).

One of the things I like about web developing with Ruby on Rails is that it comes with rake tasks that will go through the code and show you all of those notes. It recognizes the two I mentioned above, plus optimize (which I should use but I keep putting that stuff in as TODO. Bad habit) and even has an ability to look for custom ones.

That’s wonderful but not portable enough. The whole world recognizes TODO and FIXME. (At least, the whole English speaking world of programmers who read the same kind of reference materials I do). Custom tags, by definition, will be mostly only recognized by the individual or team that uses them. Especially for very large or distributed projects (like a lot of open source stuff), it would be better for the world to agree on an expanded vocabulary of meaningful tags.

I would humbly (or not) propose a few for consideration by the programming community.

• SEC or SECURITY — meaning, there’s a hole here and if don’t fill it, you’ll have no one else but yourself to blame when you get hacked.
• REMEMBER — Use this for reasons why things are done in a particular way. Like REMEMBER: The user’s are only allowed to do this on alternate Tuesdays. It was trying to use this one that made me think we needed more.
• DTU (DRY This Up. Dry stands for “Don’t Repeat Yourself.” It’s a principle that makes code more efficient and easier to figure out and maintain. It can be carried too far but so can beer drinking. No, really! Trust me on this one.
• REQ or REQUIRED — As in “Don’t blame me. The boss  insisted I do it this way.”
• LEAVE — Use this for things people will be tempted to change or remove but something will break if they do.
• IDIOT — May be a comment directed at yourself or the person who wrote the code. Exclamation point optional. No further explanation is necessary.
• OHNO — Interchangeable with “I wish I hadn’t done it this way.”
• SMITW — “Shoot Me If This Works.” Counting how many times this one shows up per program (or per 1,000 lines of code) might give some interesting or even scary results. Guaranteed not to correlate in any meaningful way with bug reports.

There. That’s a good start. I hope the programmers of the world find them useful. Oh! There’s one more that should probably go at the bottom of some blog posts, as well as in many programs:

• WWT — “Written While Tired.” Not to be confused with WWD (Written While Drunk) which is assumed for anything written in Java and all college programming courses and it still isn’t a good enough excuse.

Thanks for considering my suggestions. Pass them on and have a nice evening.

WWT.

Tags: geek stuff, programming, rails

This entry was posted on Wednesday, September 16th, 2009 at 6:54 pm and is filed under programming. You can follow any responses to this entry through the RSS 2.0 feed. You can leave a response, or trackback from your own site.