Twice within the last week, I’ve found an easily preventable bug in my code. The problem, in both cases, was that I put a TODO comment in the code, fully intending to come back later and fix up whatever issue I put the TODO in for. If you’ve developed software for any amount of time, you know the rest of the story. I never went back in, completely forgot about the TODOs, and blissfully shipped the code. Over a year later, my forgotten TODOs came back to bite me in the form of bugs. Luckily for me in both cases the bugs were very minor - but still quite annoying.

TODOs in code should be considered harmful. They’re bugs waiting to happen, and they’re so easy to forget about. There’s a sort of pathology I see a lot in code in which the author hits a particularly sticky problem (or perhaps just something they can’t be bothered to do) and they just slap in a big TODO comment. For me, no more TODOs. They’re not visible enough, not noticeable enough, and they’re a lame excuse for not doing the right thing in the first place.

There are a couple of better alternatives to TODO comments. The first is to instead file a new bug against yourself to fix whatever issue you would have written the TODO for. This has much better visibility than TODOs. It also allows you to estimate, prioritize, and schedule the needed work. Depending on your tools, doing this will range from cumbersome to elegant. A very nice IDE/issue tracking integration feature would be to allow for creating new issues from within the IDE, in the context of a file that you’re editing.

Another alternative is to write some quick, naive code that is observably incorrect. Again, this has much better visibility than TODOs, since anyone using the software should be able to tell at a glance that things aren’t right. Throwing an exception would fit in this category, as long as the exception is observable to a user/tester of the software. However, in most cases you want to write code that actually works, but has some behavior that reminds everyone that additional work still needs to be done before the feature is complete. This allows testing / other work to progress, but doesn’t allow the issue to fall off the radar.

If you do testing or QA, here’s an easy way to find bugs. Take a look through your codebase for TODO comments. For each comment you find, determine if the comment is 6 months or older, if the author of the comment is no longer with the team, etc. For those comments that have fallen by the wayside, there’s an excellent chance you’ll uncover some bugs around them. Personally, as a developer, I am going to be much more disciplined about not using TODO comments in my own work.

Further reading:
Point: http://c2.com/cgi/wiki?TodoCommentsConsideredHarmful
Counterpoint: http://c2.com/cgi/wiki?TodoCommentsConsideredUseful

In the fictional world of Star Trek, the Prime Directive is a principle at the heart of Starfleet and the Federation. This principle says that developing species shouldn’t be interacted with until their development reaches a point at which their species can interact with the Federation as equals. It is a principle that overrides all others, and violating it is the highest offense.

I hereby propose a Prime Directive for software development. This simple principle should be followed for all of the development you do:

Never engage in speculative development.

Speculative development is when you go off and spend significant time writing code that does not satisfy a known need, or that does not add value to the business you are writing code for. Unfortunately, this practice is all too common in the software industry. I’ve been guilty of it myself many times, and I’ve seen it happen on every single project I’ve worked on.

If you are writing code in the employ of a company, speculative development is not ethical. The reason is that someone is paying you to add value to their business, and speculative development does not add value. In fact, speculative development often subtracts value, since it creates more code, the potential for more bugs, and can create higher maintenance costs for a product.

There are several common manifestations of speculative development. Perhaps the most well-known is premature optimization - a well-known phrase made popular by Donald Knuth. When you spend time writing complex code to satisfy unknown or imaginary performance requirements, you’re engaging in speculative development. For most business and shrinkwrap software being written today, performance is not the primary concern. Even when performance is a concern, no software developer can intuitively know where the performance bottlenecks in their code lie. To avoid this kind of speculative development, follow this maxim: first make the code correct, and then, only if necessary, make it faster.

Another common example of speculative development is framework development. We’ve all seen this: you’re on a project, and someone on the team goes off and writes a framework to solve some problem orthogonal to the domain you’re writing code in. Most of us will admit that we’ve been that person on a number of occasions. As I’ve observed the framework writing phenomenon many times, I’ve come to realize a few things about it. First, it is often well-intentioned. We end up writing frameworks because we hate code duplication. Here’s the problem, though: we often end up spending more time writing the framework than we would have spent maintaining a small amount of duplicated code. Another reason framework writing happens so frequently is that it is interesting work. Most developers enjoy creating abstractions and coming up with new models for problems, especially when other work to do is boring and mundane. To avoid framework writing, consider whether a situation really warrants creating a framework. Often, you must accept a small amount of code duplication or impurity in your design - that’s just the nature of imperfect development environments. I promise your customers won’t know, and they will benefit more if you put that effort into other areas.

A third kind of speculative development that I see a lot is engaging in endless what-if scenarios when writing code. Don’t misunderstand - I’m not arguing against design or a thorough considering of edge cases. The difference is that you have to know when to stop. At some point, you have to decide what the boundaries of normal use for your application are. You’ll never be able to write code robust enough to cover all of the edge cases outside of those boundaries, and for most businesses, it’s not efficient to try to cover them. Filling your code with obscure edge case handling makes for very fragile and hard to maintain code. To avoid playing the what-if game, ask yourself how likely these edge scenarios really are. How will the business be impacted in the unlikely event that one of these scenarios occurs? Establish firm boundaries, and decide to let go of scenarios outside of them. Don’t make your software worse for 95% of your users in order to provide a hypothetically better experience for 5%.

The key to all of this is to think consciously about everything you do as you write code. With every piece of work, ask yourself if you’re adding value to your codebase, your business, or your problem domain. Ask yourself why you’re spending time on this particular activity and what the alternatives to it are. Analyze the alternatives, and investigate whether any of them add more value. If you get in the mindset of constantly evaluating your work and looking for ways to add value, the amount of speculative development you do will vastly decrease. Pretty soon, you too will agree that this is the Prime Directive of software development:

Never engage in speculative development.