Tracking code comments with Task List

Intro

I discourage the use of code comments (no keep reading please), because they are unmaintainable, don’t force you to write readable code and are often written so poorly that they don’t reveal intent anyway. I’ve written about this a while back [1].

Having said that, sometimes you want to add some code comment for various reasons. So if you’ve depleted your other options (refactoring so the code can be read on itself, XML documentation, etc…) then if you must write code comments, wouldn’t you then prefer trackable code comments?

Task List

In Visual Studio you can track your code comments in the Task List window by using certain tokens in your comment (for instance: “//TODO Water the plants”). If you don’t see your Task List you can open it by clicking View and then Task List in your menu (ctrl + W,T):

tasklistmenu
Figure 1: View –> Task List (your menu may be different)

Once you’ve clicked this menu item you’ll see the Task List window at the bottom of Visual Studio by default:

tasklistview
Figure 2: Task List window

Side note: Ignore the icon in front of the “UNDONE” token for now.

In figure 2 you can see some of the default tokens I’ve used, namely: “UnresolvedMergeConflict”, “TODO”, “HACK” and “UNDONE”.

Side note: You can change the sort order, reorder columns and show/hide columns. You can also navigate to the next and previous task in the list. [2]

Tokens

You can view, edit or even add these tokens at the Tools and then the Options menu item. And then at the Task List item under the Environment item in the Options dialog. Per default Visual Studio has the following tokens:

tasklistoptions
Figure 3: Options dialog

Side note: “UNDONE” is not entirely default in figure 3 which I’ll get back to.

As you can see tokens have unique strings (like “TODO”), but also priorities. This changes the icon in front of a token in the Task List and their order in the list. You’ve got ‘normal’ priority, which does nothing. You’ve got ‘high’ priority, which will display a red exclamation icon in front of the token and will make these types of comments appear first in the Task List. And you have ‘low’ priority, which will display a black downwards arrow in front of the token and make comments of this type appear at the bottom in the Task List.

Side note: The “TODO” token appears to be the only one you can’t mutate. This kind of spoiled my plan to change all the tokens to include the “:”, because this looks much better in your Task List. Oh well…

Custom Tokens

You can also add your own tokens. Just type in a new name at the “Name” textbox and the “Add” button will be enabled. Adjust the priority if you want. Click the “Add” button and then click “Ok” to close the Options dialog. I’ve added “CRIT” (critical) and made the priority ‘high’.

I’ll first show the code listing so far which uses all the tokens (including the custom one):

code
Figure 4: Complete code listing

Which makes the Task List look like:

tasklistview2
Figure 5: Task List with custom token (and a shortcut)

You can see all the tokens at play with on the top the ‘high’ priority tokens “CRIT” and “UnresolvedMergeConflict” and on the bottom the “UNDONE” token, which I’ve set to ‘low’ priority.

Shortcuts
But what’s that highlighted line in figure 5? Have you noticed how that’s just a line of code with no token? That is because this is the last capability of the Task List I wanted to show in this blogpost called: “Shortcuts”. I actually didn’t show you everything at figure 4 (so mean of me). If I may direct your attention at the following screenshot:

shortcut
Figure 6: Shortcut in code

Check out the icon at line 20. That is a shortcut which makes the line of code appear on your Task List. All you have to do is double click on it in your Task List and you’ll jump to this line of code from wherever you are in your solution. You can make shortcuts by placing the cursor on the line of code where you want it and then click on the Edit, Bookmarks, Add Task List Shortcut menu items.

User Tasks

Per Visual Studio 2015 “User Tasks” no longer exist. And in my humble opinion this is a good thing. Let devoted tools like TFS or Jira keep track of your tasks. They do a much better job at it.

Links:

  1. XML documentation: https://dannyvanderkraan.wordpress.com/2015/11/18/increase-productivity-with-xml-documentation/
  2. Using the Task List: https://msdn.microsoft.com/en-us/library/txtwdysk.aspx
Advertisements

About Danny

Bachelor in Commercial ICT MCTS Winforms .NET 2.0 MCTS ASP.NET 3.5 PSM I
This entry was posted in Visual Studio and tagged , . Bookmark the permalink.

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s