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 a 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:
This is most easy:
- First, place the cursor at the line you want to create your TODO comment in.
- Second, create a line comment (Ctrl+Slash).
- Third, after the # sign, generated by PyCharm, type TODO or todo, followed by some meaningful text.
PyCharm recognizes such comments and automatically displays them in the TODO tool window (Alt+6 or View→Tool Windows→TODO).
To learn how to work with the PyCharm's tool windows, refer to the section Using Tool Windows
Note the blue navigation stripes along the right gutter - when you hover your mouse pointer over such stripe, PyCharm shows a balloon with the description of a TODO item. When you click a marker, PyCharm immediately navigates to the corresponding line.
The other option is to use the TODO tool window. You can either use the context menu command of a TODO item Jump to Source, or select an item, and press F4, or just double-click an item. The corresponding file opens in the editor, and the line with the TODO comment gets the focus.
Comments can be used in all supported file types as long as PyCharm can recognize them. By default, PyCharm comes with two TODO patterns: it searches for either the word "todo" or the word "TODO" in comments. Once a pattern matches, the corresponding TODO item shows up in the TODO tool window.
So, you have created TODO comments with the default settings. But what will you do, if you are not happy with the color of the TODO comments, navigation stripes, or the text of your TODO pattern? In this case, PyCharm helps you configure your own style of comments.
Let's specify an additional pattern. On the main toolbar, click to open the Settings dialog. Then, under the IDE Settings, click TODO to open the TODO page with the default settings:
Suppose now that 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. This how it's done.
In the Patterns section, click , and type the following regular expression:
Besides that, let's also change the icon and color scheme:
When you apply changes, PyCharm will first re-scan your entire project for the new comments. As soon as the comment that matches your new pattern is encountered, it is rendered according to the new color scheme and appears in the TODO tool window:
Why do we need filtering of the existing TODO items? For example, we want to see only those TODO items that relate to reviewing code, and hide all the others.
To create a filter, click in the TODO tool window, and choose Edit Filters:
(Actually, this can be done also in the TODO page of the Settings dialog: →IDE Settings→TODO).
Next, in the Filters section of the dialog box, click .
Have a look at the Add Filter dialog box that opens. It shows two patterns:\btodo\b.* and \breview\b.*.
Since we'd like to hide the usual TODO items, and show only those matching the pattern \breview\b/*, let's check this pattern, and type the filter name:
Having applied changes, let's return to the TODO tool window and click again. This time we see the following commands:
So select the check command review. The TODO item that matches the \breview\b.* pattern shows in the tool window. If you double-click this item, PyCharm will immediately navigate to the corresponding line in the editor:
Let's explore an advanced PyCharm's facility to create a live template for the TODO items' text. Why do we need it at all? For example, you want your team mates to create unified TODO items, with the user name automatically filled in, followed by some arbitrary text. This is how it's done:
First, open again the Settings dialog, and under the IDE Settings section, click Live Templates: →IDE Settings→Live Templates.
Next, create a new live template: click , and type the template abbreviation and, for your convenience, description:
Note that the new template is added to the automatically created group user.
Next, pay attention to the red note at the bottom. It says that the new template lacks context, where it should apply. So let's click the link Define, and allow all possible contexts.
And finally, let's define the body of the template itself: in the area Template text, type the following:
We have two undefined variables here: $WHO$ and $TEXT$. The variable $TEXT$ will be used just as an input field, while the variable $WHO$ should be filled in automatically. To define this variable, click the button Edit variables:
Then, in the Edit Template Variables dialog box, select an expression for the variable $WHO$:
Now let's make sure it works Back in the editor, create a line comment, type rv, and press TAB:
Then type the desired text in the red frame, and press Enter:
As you see, live template has automatically populated the user name, leaving us with the task of just entering some meaningful comment.
Read the online help for more information. For example, the section Using TODO items provides details about TODO comments; description of the TODO page can be found here.
To learn more about live templates, read the section Live Templates; for the list of the supported functions refer to the dialog description.
If you want to learn how to make use of the tool windows, read the section PyCharm Tool Windows