There will be no "later".

One of the more peculiar things you often see in source code is when programmers write messages to their future selves.  In the shape of TODOs or even excuses for why the code is not done properly and how they are going to come and clean it up later.

I'll let you in on a secret: there will be no "later".  Most unfinished code is going to remain unfinished to the day it is replaced or becomes irrelevant.
 If you don't do it properly now, you are not going to come back later and put things right. You have just one shot at doing it right.

Because it is never a good time to get things done properly.  That green field on the other side of the release isn't there.  It is a mirage.  Because when you get there you are going to waste the first part of it on distractions, and you are going to spend the second part of it running around like a headless chicken with your ass on fire producing even more unfinished code in time for the next release.


  1. While this can be the case, I disagree with the generalizations that (1) time for revision never comes and (2) fast and limited but functional is "not done properly" or merits "excuses."

    I regularly address wish list things when I revisit code to make critical fixes, and it's useful when I (or anybody) needs to go and replace or refactor the code.

    Sometimes code just needs to get running, and what at first seem like important things to address may become irrelevant in real use.

  2. @salsa: then you belong to the minority of programmers who actually iterate over their code regularly to tighten things up. most programmers do not. worse yet: most programmers would not even admit this to themselves it seems (or at least they will not admit to others that they are sloppy).

    after seeing a lot of projects accumulate long-lived TODOs for things that would have taken very little effort to do properly I've begun pondering writing a tool for tracking the life of TODO/FIXME/XXX over time.

  3. So would you be writing that tool now or "later"? ;)

  4. A "TODO" is a requirement - or not.

    A developer may be the one to make the observation and to make a note of it, but this note should be visible to the whole team, not just the one other person unfortunate enough to stumble across it in the code when debugging a catastrophic bug at 3 am on a friday night the first week into production.

    TODO-messages to the developer´s future self should IMHO be taken just as seriously as a a stakeholder´s message to the developer in the form of a formal requirement. This also applies to passive-aggressive developer-to-developer messaging attempts in code (usually takes the form of comments such as "WTF?!?", "Holy mother of God!", "Jeeesuz…" etc.)

    TODOs are a nonfunctional goldmine for any requirements manager. Why not scan the code and add them to the backlog to get a true picture of the state of affairs ?

    If the TODOs reside in code only, they will be absent from all project management tools and status reports. Still they hint to unresolved (most likely nonfunctional issues) issues that the test regime may or may not disclose - before someone on the basis of the same reports gives a green light to go in to production.

  5. @Mike: when I have figured out a way to do it efficiently and correctly track the life of a TODO-message given that a source file has insertions, deletions and changes. also it should have some mechanism for tracking changes to TODO-messages. (a colleague also suggested that there should probably be a normalization mechanism that rewrites TODO messages to some normal form. for instance the form we used in our previous life.

    when I feel I have a good enough strategy for the above I might do it. unless I discover that someone else has made a tool that will function appropriately. :-)

  6. @Hans Jørgen: one thing I didn't go into was the qualitative differences in TODO messages. for instance with regard to specificity. some TODO messages are very focused and clearly state what needs to be done. others just make loose quality judgements of the code with a vague promise of improvement.

    another thing I didn't go into was the lifecycle of TODO messages. there are clearly legitimate uses of TODO messages, but those usually fall into the category of short-lived TODOs. subjective judgement of a lot of code I have seen over the past decade suggests that if a TODO isn't addressed within the first week or two of being put in the code, the chance of it being addressed drops to nearly zero.

    I completely agree that there should be a tool that tracks TODO messages and that the extracted knowledge should factor into the planning process.

    this is why I am a bit interested in a tool that could track TODO messages -- to understand the individual developer, to understand certain types of behaviors, to compare to other factors (such as defect rates).

    it would be interesting to have a tool that can do this retroactively as well as on an ongoing basis. for instance so you can apply it to a source code repository and construct a timeline for TODOs, but also so you can hook tracking of TODOs into post-commit hooks.