Take the 2-minute tour ×
Programmers Stack Exchange is a question and answer site for professional programmers interested in conceptual questions about software development. It's 100% free, no registration required.

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?

share|improve this question
3  
Whenever I think of a task to be done or edge-case that needs to be checked for the current feature I'm working on, I stop what I'm writing (even mid-statement) and add a TODO for it (even if it's just the line above). This helps prevent those "Oh yeah, I even thought about that" bugs. Before I commit the feature, I check the TODOs. They never get committed, but since I've started doing this my number of bugs has gone down drastically. –  BlueRaja - Danny Pflughoeft Dec 15 '11 at 17:54
1  
I always use #warning TODO: … if I don't want to forget the TODO. –  rightfold Dec 15 '11 at 19:10
show 6 more comments

16 Answers 16

up vote 81 down vote accepted

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).

share|improve this answer
12  
Eclipse highlights them and consolidates a list of them for you as well. And writing a TODO comment while the thought is on your mind is not a bad idea, even if you never get around to actually DOing it. Some magnanimous soul may actually be browsing the code looking for things to do (OSS). –  hobs Dec 15 '11 at 14:08
3  
Resharper has a nice listing of TODOs as well, it works better than the default VS one (looks in more files). –  CaffGeek Dec 15 '11 at 14:56
3  
Because of comment rot, I always date and initial my comments. If the comment is three years old from four contractors ago, you can probably delete it. –  user1936 Dec 15 '11 at 17:40
show 4 more comments

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.

share|improve this answer
18  
I think the date and owner of the TODO is just noise. That's what version control (and the blame feature) are for (if you really need the information). –  sleske Dec 15 '11 at 11:30
2  
I don't think a wikipedia that says "It is adviced" is any citable; smell alert. Better link to the article that claims this. –  phresnel Dec 15 '11 at 12:29
1  
Visual Studio's "annotate" feature makes it easy to see who last checked in changes to various parts of the file you are working on, and by which changeset. Not perfect, but in many cases (particularly with TODO comments) close enough to be useful. –  Michael Kjörling Dec 15 '11 at 13:04
show 8 more comments

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.

share|improve this answer
3  
"FIXME" and "TODO" have different meanings for me. A translation, a hard-coded value, or a catching an exception with ex.printStacktrace() are TODO for me. On the other hand, FIXME would deal with Exception that occur sometimes, a memory leak, or another type of bug that you have located but not fully analyzed/fixed. –  rds Dec 16 '11 at 10:31
add comment

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.

share|improve this answer
1  
A TODO comment is lcoalized to a line fo code. A ticket is more global and higher level, in my opinion. And I do thinnk this annotation is an overkill. TODO has more chance to work on more editors. –  rds Dec 16 '11 at 10:33
1  
Your industry? Which is that? I don't know a whole industry that encourages JIRA use?! –  phresnel Feb 7 at 15:55
add comment

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.

share|improve this answer
add comment

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.

share|improve this answer
1  
If it's been there for well over a decade, it wasn't really needed and thus adding a TODO comment made no sense. –  Michael Kjörling Dec 15 '11 at 13:43
1  
That assumes they never change. Like the code, though, comments are subject to change with additions, deletions and modifications. TODO lists are more likely to be changed in this manner. I am certain that in the last decade since I last touched the code it's comments were changed. –  Pete Mancini Dec 24 '11 at 15:43
add comment

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 :-).

share|improve this answer
add comment

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.

share|improve this answer
add comment

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.

share|improve this answer
5  
And then you insert a new function in filename.cpp, say around line 200 in the case of your example, because you find it helpful to refactor some piece of code. Suddenly your reference is meaningless. I prefer the IDE pointing them out to me where they are right now, not where they were when I saw the need TODO whatever. –  Michael Kjörling Dec 15 '11 at 13:07
show 1 more comment

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.

share|improve this answer
add comment

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.

share|improve this answer
1  
In that case you could simply throw a new NotImplementedException() which is implies a ToDo. –  CodesInChaos Mar 11 '13 at 10:03
add comment

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

share|improve this answer
add comment

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.

share|improve this answer
add comment

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'}
share|improve this answer
add comment

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".

share|improve this answer
add comment

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.

share|improve this answer
add comment

Your Answer

 
discard

By posting your answer, you agree to the privacy policy and terms of service.

Not the answer you're looking for? Browse other questions tagged or ask your own question.