Managing TODO comments in your code
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.
http://www.youtube.com/watch?v=VV1aIz6D5wk
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
