Managing TODO comments in your code

Mikhail Vink

Working on a large project it is quite usual to leave some code refactoring or improvement tasks to be done later, have some code left to be reviewed by your colleagues or just mark some places you still have questions about. Especially if you work in a team it is very important to keep yourself and your team informed about all the issues that require attention. Therefore, sometimes you just can’t find all the comments left in thousands of strings and hundreds of files your project contains.

TODO comments in the source code help you to keep high performance and have easy access to all the comments. It makes navigation faster and work on the code in general becomes more productive and time-efficient.

This functionality is available in IntelliJ Idea, PyCharm, WebStorm, PhpStorm, RubyMine, AppCode.

In order to add TODO comment just comment a line, block or a part of line using characters specific to language you are writing at (or use hotkey Ctrl+/ or Cmd+/ in order to have it done by IDE) and use pattern word (by default TODO) inside the comment regardless of the case. This issue will be immediately considered as TODO issue and added to appropriate section.

By default there is only one pre-defined pattern word configured, however, you are free to add as many patterns as you are comfortable with using settings (File | Settings | Patterns – detailed instructions are provided below). IDE highlights such comments in accordance with the Colors and Fonts settings.

As soon as you need to check what TODO issues you have just click on TODO button in left-bottom corner of the screen or get it with a hotkey Alt+6.

The tool window displays the encountered TODO items – there are a few options available:

  • Show everything around a whole project (Project tab)
  • Show only issues in this file (Current file tab)
  • In one of the already defined scopes (Scope Based tab) – quite useful for large projects due to big amounts of issues (Scope features might be not available for you right now, but will be presented in next release e.g. PhpStorm&WebStorm 6)
  • In the current changelist, if version control support is enabled (Changelist tab)

In a tool window you can observe all the current issues easily navigating from one to another. You can have the issues un-grouped (by default) or grouped by module/package. When the auto-scroll to source function is enabled you will be navigated to the appropriate line in the editor as soon as you click on the TODO issue.

Otherwise, having Preview Usages option enabled you will be able to observe commented section on the right without directly going to the line in the editor.

Moreover, with all the settings IDE provide it’s really easy to customize this functionality just the way you want it to work. Let’s consider how TODOs can be used for your project. We have a team of 5 people: Nick, Martha, Catherine, Bob and Sebastian working on some web project. Mostly they work on different tasks and than commit all the changes they made to Git or SVN. However, sometimes during the coding they need to leave messages to each other. It wouldn’t be so convenient to leave just TODO comment everywhere and they decide to create different TODO patterns.

In order to configure TODO issues functionality you need to navigate to File | Settings | Patterns or just click on the Filter – Edit filter button on the left.

Using the + button add as many patterns as you need, for example, we are adding patterns for every member of our team (\btodo-NAME\b.*) as well as special patterns for hack and urgent (if we need to have this issue be checked first). All the patterns can have different icons (for example red icon for urgent) and different colors.

When you are ready with patterns it is also very important to work on filters, otherwise it can be quite complicated to find yourself in dozens of TODO issues created by your teammates. For example, you are Nick now actually working as a senior developer and that means you are the most qualified member of the development team and it is your duty to work on urgent issues and to help your team.

Let’s create filters such as Me (there should go issues for Nick (you) personally as well as any other urgent and general tasks) and filters for team members (one for every of them – you basically don’t need to check them all the time so that shouldn’t include in your filter), one for general issues (non-personal) and one for personal only.

Now we are ready to increase productivity of our team through intelligent TODO issues management – it should be fast and reliable: there is no use in spending hours searching for comments left somewhere by someone, however, one forgotten issue can lead to your project being crashed after some time.

Just click on Filters button and choose what issues you need to observe.

Develop with pleasure!
– JetBrains Web IDE Team

Comments below can no longer be edited.

16 Responses to Managing TODO comments in your code

  1. Stansilav says:

    October 19, 2012

    Hello! How to make an appearance as the screenshot “main_funct_todo.png”? I want theese nice icons in my IDE! 🙂

    • Mikhail Vink says:

      October 19, 2012

      Hi! These nice icons will be available for you in the next release =) Just wait a little!

  2. Philip Serefoglou says:

    October 19, 2012

    Is it possible to exclude files/folders from this process , I mean lets say I don’t want to see the todos of a random lib I use in my project ?

    • Andriy Bazanov says:

      October 19, 2012

      It’s already implemented (“Scope Based” tab) and will be available in v6. You just need to define your own scope that would exclude unwanted libraries/folders/files.

      • Philip Serefoglou says:

        October 21, 2012

        Nice hope v6 is not too far 🙂

  3. Romey says:

    October 19, 2012

    Hello. I don’t want see ToDo in included libraries. Can you make possibility to turn off their in some folders?

    • Andriy Bazanov says:

      October 19, 2012

      It’s already implemented (“Scope Based” tab) and will be available in v6.

      • Romey says:

        October 19, 2012

        Thank you

  4. Mike Schinkel says:

    October 19, 2012

    Thanks for this writeup, very helpful.

    But we need multiline TODOs and automatic inclusion of author name and date/time for TODOs. Please. 🙂

  5. Florent says:

    October 24, 2012

    Scope-Based TODOs – finally!! Without scopes, TODOs are qute useless IMHO. Hope we do not need to wait very long for this to appear, as this is a standard in other IDEs.

    • Mikhail Vink says:

      October 24, 2012

      It’ll be available in v6 (and v6 EAP as well) – so not a long time to appear

  6. Local History and TODOs | JetBrains AppCode Blog says:

    October 25, 2012

    […] Read also the related post. […]

  7. Local History and TODOs | JetBrains AppCode Blog says:

    October 25, 2012

    […] Watch video at JetBrains TV. Read the related post. […]

  8. Niels says:

    November 1, 2012

    Thanks for the tips.

    What part of “Export settings” should I “check” if want to export my TODO settings/filters to share it with the rest of my team?

    • Mikhail Vink says:

      November 1, 2012

      Actually TODO patterns and filters can not be exported with “settings export”. Feel free to create an issue at YouTrack with new feature suggestion and it will be implemented in the future

      However, it can be copied manually. TODO patterns and filters settings are kept in XML USER_PATH/.WebIde50/config/options/other.xml
      component name “TodoConfiguration”

  9. Patrick says:

    January 18, 2013

    I love you, phpstorm. PS: I can’t wait for v6 when the ability to exclude folders comes out!