What to do about TODOs
Many projects I work on are littered with TODOs, FIXMEs, or XXXs. Some programmers use these tags to remind themselves of stuff to do later on in the project. Sometimes, these programmers also comment out whole sections of code using block comments like /*, or even an #if false. To these people I say: a source code file is not a notepad.
The problem with TODOs has to do with the maintainability of the code. If another programmer looks at a class file that contains lots of task tags, he might become confused: to what degree is this class finished? It gets even worse when someone fixes the issue that is mentioned in the TODO, but forgets to remove the tag. There is nothing left to do, but the TODO remains.
Commenting out blocks of code has the same issue: a coworker has to determine why the code was commented out. Was it because it no longer works? Or because it might be useful in the future? But hasn’t XP taught us that planning upfront is the wrong thing to do?
I suppose that using TODOs has something to do with the fact that it is hard to stamp your code with the label finished. As long as there are some TODOs in there, you always have an excuse for a bug, and you never have to take responsibility.
I try never to check in anything that contains a task tag or a large code block comment. I try to keep the code 100% finished, at all times. This doesn’t mean that it does everything yet, but it means that it does everything it is supposed to do correctly. If it doesn’t, you’ve found a bug. Clear and simple.
Steve Currency said,
March 22, 2005 @ 0:24
Lingering TODO is indeed a problem, but not huge. I personally use TODOs but as a milestone approaches, we make sure that all TODOs are moved to a more appropriate forum like Bugzilla.
TODOs are then great for putting in as you go to make sure you don’t forget anything later. You then just have to have the disipline to grep for them and take care of them when appropriate. That means before you commit or before release.
Anonymous said,
March 22, 2005 @ 0:45
I guess you haven’t ever worked on big systems. When building a use case, you often run into issues that can’t be resolved immediately. You might need a meeting or you might be waiting for information. This is what TODO’s are for. They tell you the code isn’t finished, but it is finished enough to check in.
Before a release, you make sure there are no more TODO’s in the code. Eclipse gives you a list.
Marc Logemann said,
March 22, 2005 @ 0:51
Have to completely disagree on your post. First of all, TODOs are not about bugs, its about things you can do better but dont have the time or the skill to do now. Think about a sorting algorithm which basically works but could be faster somehow. This is a perfect place for a TODO, of course you should allways use a bug/defect tracking tool to further express that you need to work on that sometime.
Comenting out blocks is also perfectly valid for scenarios where you want to test something but dont want to remove an alternative way of doing things. You can argue that in a versioned world, you can retrieve the old stuff anyway, this is true, but sometimes its easier to leave this in the code for some beta releases or whatsoever. Later on you should indeed remove it completely.
But when reading other peoples code, seeing this kind of stuff is definitely one of the smallest anoyances i can imagine.
Roland Chan said,
March 22, 2005 @ 16:58
I have to agree with the poster. You should be checking in regularly code that is doing exactly what it is supposed to do. Not what you’re hoping it should do or planning on it to do.
If you’re tempted to write a TODO and practice unit testing or better yet TDD, then your better off writing a failing test. This is better than any ambiguous documentation that might unknowingly be misinterpreted by your colleagues.
This is perfectly valid for the algorithm improvements the previous commentor made. If I can think of some measurable way to improve the algorithm and write it down in the form of a javadoc, then I’m probably well equipped enough to write a unit test for it.
If I’m completely stumped on the requirement then I’ll flag the use case or user story for follow up, or raise this as a risk to be reviewed during the project steering process.
I blogged about this too last month: http://www.thechanfam.net/wordpress/?p=24
Arjen said,
March 22, 2005 @ 17:21
Anonymous, I have worked on big systems, and I prefer to do them in an XP-fashion. This means that I’m constantly adding features (stories) that the customer requested. Even though these features change stuff accross all layers, I commit them as a whole. Thus, the system as a whole is always in a workable state, and doesn’t require reminders. If it does, I use a external system, such as JIRA.
Michael Slattery said,
March 22, 2005 @ 20:05
I agree. TODO’s are litter. I use them a lot, but I remove them BEFORE CHECKIN. If you need them there longer than that you should record them in a tracking system (like Bugzilla). Put code blocks you would have commented out into the tracking system.
The goal you achieve: organization of your thoughts and your code.
Paul Gielens said,
March 25, 2005 @ 23:57
Keep your code clean from todo’s and fixme’s. If the code isn’t worth to improve on the spot, then why bother wasting precious time commenting (and hoping your comment is readable for other humans) instead of fixing whatever needs to be fixed. At least take the time to check or write a unit test to prove your finding.
Steve Currency:
“Before a release, you make sure there are no more TODO’s in the code. Eclipse gives you a list.???
What company you work for? This sounds as the ideal world to me, most of us mark “release??? as crunch time and squashing bugs has priority over todo’s at our house.
Marc Logemann:
Seriously if you need fragments of code to “test something out??? you have no clue what your doing in the first place. To give an example: Recently I removed about 30% of unused/obsolete code in our project because one of my colleagues used the same (I’ll get that later) approach.
You should get yourself a copy of Resharper and (just for fun) run through your code. You’ll be surprised