Developers in most projects I have seen try to establish some sort of convention around leaving TODOs in the code. The most common seems to be “if you see something funny, try to fix it immediately, but if it’d take too long and you’ve got something else to worry about, leave a comment next to it starting with TODO, your initials and maybe a date”.
You know what? Using comments for that is not as cool in Ruby, Python or Java, which has had static imports for a while now. How about creating a TODO method that takes in the initials, date and comment text, or whatever else you might find useful?
import static my.project.DevelopmentUtils.TODO;
...
public void doStuffThatSmellsFunny() {
TODO("CV, 21/jan", "Clean this mess up after fixing #3849");
...
}
There are some advantages to this: you can actually put some code inside that method to do, say, logging. Another good thing is that now the TODOs can be tracked using the same refactoring tools and features of modern IDEs as just any other code in the project.
It may seem a bit cumbersome, but I’ve been trying that for a few days now and it feels quite pleasant to use. I got my TODO method to just spit out the message to the console so when I run tests, I can quickly get an idea of what areas of the code touch stinky or incomplete ones.
Anthony Eden | 06-Jun-07 at 2:19 pm | Permalink
That’s actually a pretty cool little idea. I think I’ll give it a try.
Ricky Clarkson | 06-Jun-07 at 2:32 pm | Permalink
It looks like it should be an annotation to me – not something that actually gets executed.
Sam | 06-Jun-07 at 4:36 pm | Permalink
Maybe you could even break the build if a TODO is older than a few months. That way it’ll force you to make decisions about todo’s that are hanging around.
Guilherme Chapiewski | 06-Jun-07 at 6:02 pm | Permalink
Sounds good. This seems also to prevent TODOs from never leaving the code (which happens very frequently).
Brian Guthrie | 06-Jun-07 at 6:47 pm | Permalink
That’s a great idea. You can even extend it to automatically detect the current method or class, by using a method_added callback in class Class, or generating the appropriate method handle from call_stack. You could also use call_stack to find line numbers and generate HTML output or something.
class Foo
TODO :btg, “1/1/2007″, “fix this”
def broken_method(…)
end
end
Foo.todos #=> { :broken_method => “fix this” }
Tom Adams | 06-Jun-07 at 10:11 pm | Permalink
I use a similar idea on Instinct, but instead of methods, I use annotations. I have two, Suggest which is for suggestions for improvement, and Fix, which is for things that are broken & need to be fixed. You can even tie the fix comments to a release number, implying they need to be fixed before the release is out. This is one way of making sure not too many of them get out the door & the number doesn’t keep increasing. I don’t have the release build failing yet if there are fixes left for that release, but it’s planned.
One of the good things with this is that you can embed strongly typed information into the annotation, such as story card details, pair information, etc. You can also easily track it using find usages in your IDE.
Here’s an example of a Fix: http://instinct.googlecode.com/svn/trunk/core/src/main/java/com/googlecode/instinct/expect/ExpectThatImpl.java
And here’s a Suggest: http://instinct.googlecode.com/svn/trunk/core/src/main/java/com/googlecode/instinct/runner/StatusLoggingContextRunner.java
Tom Adams | 07-Jun-07 at 12:11 am | Permalink
I use a similar thing on Instinct, but instead of methods, I use annotations.
I have two, Suggest which is for suggestions for improvement, and Fix, which is for things that are broken & need to be fixed. You can even tie the fix comments to a release number, implying they need to be fixed before the release is out. This is one way of making sure not too many of them get out the door & the number doesn’t keep increasing. I don’t have the release build failing yet if there are fixes left for that release, but it’s planned.
One of the good things with this is that you can embed strongly typed information into the annotation, such as story card details, pair information, etc. You can also easily track it using find usages in your IDE.
Here’s an example of a Fix: http://instinct.googlecode.com/svn/trunk/core/src/main/java/com/googlecode/instinct/expect/ExpectThatImpl.java
And here’s a Suggest: http://instinct.googlecode.com/svn/trunk/core/src/main/java/com/googlecode/instinct/runner/StatusLoggingContextRunner.java
Master of Nothing | 07-Jun-07 at 12:16 pm | Permalink
Very interesting approach indeed. I have used //TODO comments extensively when developing in Java and I was able to track them easily in both Eclipse and IntelliJ IDEA. Comment approach was good but it never forced you to address the TODOs like what you have suggested
.
Sidu | 07-Jun-07 at 12:59 pm | Permalink
IntelliJ can parse TODO comments and list them (Alt+6). In fact, I think you can get IDEA to treat them as warnings in Inspections. Where it falls over is if you want this as part of your build, which is where it would be really useful. Nice idea!
chris clarke » Getting your TODOs out of comments | 08-Jun-07 at 10:12 pm | Permalink
[...] Thoughtworker Carlos Villela talks about Getting your TODOs out of comments. [...]
Fernando Boaglio | 11-Jun-07 at 1:12 pm | Permalink
Since Eclipse can easily list all my TODO comments I never thought about that.
Using your method you can use a “priority” approach (just like Bugzilla) which can solve my problem: where should I start fixing my code?
Steve Freeman | 22-Apr-08 at 4:00 pm | Permalink
Another Smalltalk idea rediscovered… In those days it was the best way to search the image.