When working on a project, it's often needed to create a list of tasks for yourself or your team mates. While usually these tasks are described in an issue tracker like , some tasks are either too small or too code-specific to describe in an issue tracker. In such case, adding todo comments in source code makes sense.
Many developers already use comments in their code to describe these small tasks, typically using a statement like the following:
PhpStorm recognizes these comments and will automatically display them in the TODO tool Window (Alt+6 or View | Tool Windows | TODO).
From the TODO tool window, we can select a todo comment and navigate to it by double-clicking it or using the Jump to Source context menu (F4).
Comments can be used in all supported file types as long as PhpStorm can recognize them. By default, PhpStorm comes with two TODO patterns: it searches either for the word todo or the word fixme in comments. Once a pattern matches, the TODO will show up in the TODO tool window.
From the PhpStorm IDE settings | TODO, we can specify additional patterns. Imagine we want to have a code review for specific lines of code when a comment containing the word "review" is found. We can do this by adding a TODO pattern, a simple regular expression search:
We can now use this pattern in our code to add todo comments for code reviewers:
Note that only the word "review" is colored in this example. The reason for that is our regex only matches the word "review" and not all text thereafter. If we change the regex pattern to "\breview\b.*", the entire comment will be highlighted instead.
From the TODO tool window, we can select a todo comment and navigate to it by double-clicking it or using the Jump to Source context menu (F4). In this tool window, we can also use the preview toolbar switch to see a preview of every todo in the TODO tool windows.
When working in the editor, we can navigate between todo comments using the Ctrl+Alt+Up/Down (Cmd+Alt+Up/Down on Mac) keyboard shortcuts.
When working in a large project, the list of todo comments may grow large. We can filter todo comments by adding a new filter through the IDE settings | TODO using the Add filter button. For example, we can create a filter for the review pattern created earlier in this tutorial:
From the TODO tool window, we can now click the filter toolbar icon and specify which todo comments we want to see:
When working on a project with a team, it may make sense to have user-specific todo's. Using filters, we can add a pattern and filter for every user on our team. For example when the team has three members, we can create the following patterns:
Adding filters makes sense as well. This way, we can easily find out the items we have to work on:
Note that by just adding the name of a team members (for example in square brackets) in the TODO patterns, we don't have to create additional filters for possible TODO filter created earlier (todo, review, fixme, ...)
Creating todo comments can be done by simply typing them. We can also make a live template which helps creating a todo comment in code. Under the PhpStorm IDE Settings | Live Templates, we can create live templates for specific todo comments. For example, this one may work for a code review:
By adding live template variables and adding the username using the user() expression, we can now simply type // cr followed by TAB and have our live template expanded:
The live template will auto-populate the username and allows us to just type the description of the todo comment.