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 YouTrack, 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.
Creating TODO comments
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 in the editor by double-clicking it or using the Jump to Source context menu (F4).
Working with TODO patterns
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.
Navigating between comments
From the TODO tool window, we can select a todo comment and navigate to it in the editor 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.
Filtering TODO comments
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:
Filtering TODO comments by team member
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:
We can now create filters that show us the TODO comments applicable to ourselves, our team members or any other patterns we have defined:
Filtering TODO comments by scope
In large projects or when working on a code base that contains a lot of TODO comments, the list shown in the TODO tool window may become overwhelming. To overcome this, we can filter TODO comments by scope.
From the TODO tool window, we can specify the scope for which we want to see TODO comments:
- For the entire project (Project tab)
- For the file that's currently acive in the editor (Current File tab)
- For a predefined or custom scope (Scope Based tab)
Here's an example where TODO comments for the Current File are shown:
Creating TODO comments using live templates
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.