Who hasn't seen things like:
//TODO fix after June
(But that comment was checked in 2 years ago)
//TODO see Fred for a fix.
(Fred doesn't work there anymore, by the way).
Amongst the many code quality techniciques and policies, such as unit testing, treating warnings as errors, and using static analysis tools, I propose a system for dealing with a "TODO" - something that has been identified as needing rework eventually.
In my Android Game, I have recently started using a class to denote such beasts. Behold:
//TODO optimize/minimize allocations....
Now, whenever I feel the need to write a //TODO comment, I accompany it with a construct like above. This is in Java, in C++ or C# you could get a little fancier. I check a static final "FailTodo" flag outside of the call to give the compiler an optimization hint. This is the closest thing to an #ifdef you will find in standard Java. If the flag is false, as it is normally, the compiler just optimizes it all away, so you don't pay a price when you're not using it.
The body of the todo method simply throws an exception:
public class DebugHelp
public static final void todo(String todoText)
throw new RuntimeException("Failed TODO: " + todoText);
A C# variant of the same thing would be:
public class DebugHelp
public static void Todo(string todoText)
throw new InvalidOperationException("Failed TODO:" + todoText);
A little cleaner, since I can call Todo directly without the flag check, and the compiler will optimized it out if the "FAILTODO" is not defined at the project level.
On more example for the C++ playas in the house:
#define TODO(x) ASSERT(false, "Failed TODO: " x);
(or insert your own assert mechanism, every good project has one :) )
The real epiphany of this for me was not the trivial implementations I showed, but the general concept of a checked "todo". These are things that really should not be in comments, where they are summarily ignored. Before shipping, or when I enter the next cleanup/optimization pass, I can deal with these issues. You could also hook this into an automated testing or regression system.
P.S. (Ignore what I actually do in my implementation of 'todo' or my "exception correctness", they're contrived examples for this post.)
Post a Comment
I welcome you're thoughts. Keep it classy, think of the children.