Do TODO comments make sense?

Question

I am working on a fairly big project and got the task to do some translations for it. There were tons of labels that haven't been translated and while I was digging through the code I found this little piece of code

//TODO translations

This made me think about the sense of these comments to yourself (and others?) because I got the feeling that most developers after they get a certain piece of code done and it does what it's supposed to do they never look at this until they have to maintain it or add new functionality. So that this TODO will be lost for a long time.

Does it make sense to write this comments or should they be written on a whiteboard/paper/something else where they remain in the focus of developers?

Answer 1

I tend to use // todo comments for things that have to happen, but I can't do immediately.

I also make sure that I chase up on them - I search for them (Visual Studio has a nice feature where it will list such comments for you) and ensure that things are done.

But, as you say, not everyone is diligent about them and like many comments, they tend to rot over time.

I would say this is more of a personal preference - so long as you document what needs to be done and chase up on it, it doesn't matter if it is in // todo, postit notes or a whiteboard (where they can also end up not being actioned).

Answer 2

Modern IDEs recognize the TODO comments and they are as such visible in their own panel/window/tab, so they are theoretically not lost (I'm thinking Eclipse and Visual Studio, both I know enough to remember that they recognize it).

You can even configure additional comment words such as FIXME, BEWARE or anything else you want to customize. However, other developers on your project will have to customize their IDE the same way.

Now, I wrote "theoretically" because although not lost, the TODO more than often relates to something that is not needed for the application to work properly "at the moment". And "at the moment" may extend for 5 minutes to 5 years, depending on the type/size of the project :-)

Finally, in my opinion it still makes more sense to have them in the code, at the right place, precisely answering the question "where should I make the change" than somewhere else outside of the code.

Edit: As it is written in Wikipedia's article on comments, including the date and owner of the TODO is considered to be a good practice.

Answer 3

It may make some sense, at least I use them sometimes. The key point is to use consistent tags such as TODO or FIXME so that they can be easily found with simple text search.

For example, "quick 'n dirty" solutions are convenient to label, something like:

ConnManager.getConnection("mydatabase"); // FIXME: DB name should be configurable

If the code does what it's supposed to do, and nobody complains, then the comment does no harm. If there ever is time to beautify the code, it's easy to start with searching for FIXME labels.

Answer 4

In my industry, developers are encouraged to make JIRA (or etc) entries instead of todo comments because not everybody gets a chance to see the // todo entries. But sometimes in large projects a custom attribute gets defined along the lines of:

[AttributeUsageAttribute(AttributeTargets.All, AllowMultiple = true)]
public class DeveloperNote : Attribute
{
    public DateTime EntryDate { get; set; }
    public string Description { get; set; }
    public DeveloperNote(int year, int month, int day, string desc)
    {
        EntryDate = new DateTime(year, month, day);
        Description = desc;
    }
}

And then a method can be decorated in this way...

[DeveloperNote(2011, 12, 13, "Make the db connection configurable")]

And the higher ups can come along and harvest these automatically. It may be overkill for the simple // todo reminder, but it's effective. Also it requires a .NET platform.

Answer 5

In my experience it depends. The main factor is whether or not the team is disciplined enough to follow up on these "little" comments. If they do then yes they make sense. If they don't then these comments are just a waste of time and you may want to look into other options, e.g. story cards.

Personally I use TODO comments occasionally but they are typically just short lived and I usually have only a very small number of them like one, two or three. I use them more as a marker in the code base than anything else. If I wait too long to take care of them then I forget about what I thought I needed 'to do'.

My preference would always be to not use these and instead use proper story cards or backlogs or similar. Use one mechanism for one task.

Answer 6

I used to write them in the past, but I have found that you do not usually follow them up.

Therefore now I only use them to mark things I want to work on right after I finish what I'm busy with. For example, I implement a new function and notice that a function I use has a small bug; I make a FIXME to fix this to avoid getting derailed in my current task.

To help me, our CI builds are set up to fail if there are FIXMEs in the code :-).

If you notice potential problems that cannot be addressed right away, open a ticket/bug/issue for them. That way, they can be prioritized like all bugs. I feel this is much better than having some problems in the bug DB and some in the code as TODOs.

Optionally, you can then put in a TODO with the bug ID :-).

Answer 7

TODO is just a subform of comment. Comments have great utility if the writer is at all skilled in knowing what to convey and how to convey it. A sense of humor can also be applied here in small doses to delight maintainers years later.

I got a call last year that some of my code was being retired. I was rather impressed that it had been in production and survived maintenance for 16 years. So be aware, your code could last a LONG time. Comments on intention, future needs and so forth can go a long way in helping someone out years from now who is looking at your code for the first time.

Answer 8

If you write a TODO or FIXME with the idea that someone else will fix it when they come to that code at some indeterminate future then I'd say don't bother. They will litter the code and clutter the reporting part of your IDE that collects this information.

To be useful they should provide a means to bookmark your code for the (very) near future so that you can get back in the proper state of mind faster. In other words, you place them in your code only to remove them ASAP.

Anything longer lived should in fact be placed in your bug base where it belongs.

There is enough noise in our lives, let's not create a new fanfare of stuff that yell for attention while it is required elsewhere.

My 2 cent

Answer 9

I think TODO comments, to some extent, make sense. Particularly if you are working iteratively (as is common in agile and TDD shops), there will be things that you recognize are going to be needed before long but which you don't want to make the detour to implement right then and there.

What gets ugly is when such comments remain in the codebase. While you are actively working on a feature it's fine to leave them in, but as soon as you get closer to completing the feature, you should focus on getting rid of them. If you don't want to go through the work of actually replacing them with proper, working code then, at least factor out the relevant functionality. To borrow @JoonasPulakka's example, where the code initially says

ConnManager.getConnection("mydatabase"); // FIXME: DB name should be configurable

you might change that to something like

ConnManager.getConnection(GetDatabaseName());

with, for the time being, GetDatabaseName() being a stub that simply returns the same string that you started out with. That way, there is a clear point of future expansion, and you know that any changes made there will be reflected anywhere the database name is needed. If the database name is even moderately generic, this can be a massive improvement in maintainability.

Personally, I use a keyword of my own instead of strictly TODO, although the intent is the same: to mark things that I know will need revisiting. Also, before I check in my code, I do a global source code search for that keyword, which is chosen such that normally it should not appear anywhere in the code. If it's found, I know I forgot something, and can go ahead and fix it.

As for including the programmer name/signature with the comment, I think that's overkill if you have a source code version control system (you do, right?). In that case, its blame feature will tell you who added the comment, or more accurately who last checked in a change that touched the comment. For example, in Visual Studio, this is easily accomplished by using the "Annotate" feature found among the source control features.

Answer 10

Usually I don't make //TODO comments but keep all them in separated file. Still can't find/write online software to easy manage them so TODO files is still being most useful for me because when I open the project after even short time I forget what to do now and then I look into TODO file and do the job. I've got "filename.cpp 354 : Recode this bla bla bla" and it's much more useful then search //TODO comment in the file. I did //TODO earler when I was lazy but I just remove those old //TODO-s from source file and do not fix them when project works well. I strongly recommend to move all //TODOs from souce to separate place and keep them together with other todos so you can priority the tasks easy. Priority is really hard thing TODO when you got all your TODOs in various files and various projects.

Answer 11

The huge advantage of todo comments over any of the other million or so ways one can create a task list is that todo comments travel with the code so they can't get separated.

Probably the more appropriate place for stuff like this is the issue tracker rather than the code though.

Answer 12

I think there great, but not alone. For example:

//TODO: ADD MY CLICK EVENT LOGIC
throw new Exception();
//Even a simple messageBox could suffice

This approach works pretty nice sparingly. Although I would have to say that making it a habit of throwing exceptions to remind you to complete some code is not really the most professional approach. But it has saved me in some cases where you think you completed something and even wrote down you completed when you haven't.

Answer 13

I strongly recommend that every TODO or FIXME be entered into a formal log. If they are not, they are easily searchable, and it should be a phase in each iteration to check for outstanding TODOs and FIXMEs. These can then be catalogued, and either set for immediate remedy, or the team can plan to fix them at the appropriate time.

Finally, once fixed they need to be removed - if they are not eliminated in a systematic manner after being resolved, they will lose their effectiveness.

Bottom line: They're better than not logging issues at all, but you actually have to maintain them.

Answer 14

IntelliJ will actually alert you if you try to commit code that has new TODOs. So, you can always interpret a TODO as "this really should happen by the time I commit".

Answer 15

When you consider the "TODO" as a semantic label for your comment I think they do make sense.

In my company's coding standards, we specify that the initials of the developer responsible must be included with the TODO (i.e., I would type "SAA TODO:"). I think this is useful, at least as a convention, because otherwise there is the temptation for leaving substandard code with the TODO note for some future developer to deal with.

Helpfully, many IDEs can be configured to add these comments to a task list, allowing them to be treated similarly to build wrnings and not forgotten indefinitely.

Answer 16

A more obnoxious, yet effective method is probably to turn your todo comments into compiler messages, that way you and everyone else sees it when the program is compiled.

in Delphi:

{$message 'todo: free this thing when you know its not going to blow up'}

Answer 17

In my experience, TODO should be used to indicate that a piece of code is not usable and tells the reader what's needed to make it usable (either locally or elsewhere).

TODO annotations should not be used to indicate that some piece of code would be nicer if modified in some way. Examples include dirty code that would be more maintainable if rewritten or an extra feature that nobody needs yet. Those annotations tend pile up and make a grep TODO return useless results.