While reasonable people can choose to disagree about the value of in-line code comments for the sake of describing what the code is actually doing — many take the opinion that if your code needs comment to be clear, its not clear code — it seems that even people that are against code comments as an article of faith are likely in favor of comments related to reminding yourself and other developers about tasks that need to be done in connection with the development project.

With Visual Studio 2008, there are a number of choices as to where to place these comments and understanding where the comments are stored and how they’re shared among your team members can be an important part of deciding which place is the proper location to comment task items.

Let’s explore some of these choices in some detail so we can understand their pros and cons…

Choice 1: In the Source Code File itself

Placing comments within the actual source code file itself is certainly the traditional approach and Visual Studio 2008 out-of-the-box provides tooling to support this.  By default Visual Studio 2008 supports two keywords most developers are familiar with in code comments related to task items:

The first of these is the HACK keyword when used as the first work in a comment as in…

//HACK: this method needs to be optimized better, but this will be fine for now

The second of these is the TODO keyword when used as the first word in a comment as in…

//TODO: implement this method

If code comments like these are added directly into your source code file(s), then they can be made to appear in the Task List window in the Visual Studio 2008 IDE as in…

This approach has a few advantages:

1. The comment is (or at least can be!) located near the actual instance of the section of code to which the comment applies
2. The comment always stays with the source code, no matter what editor/viewer is employed; even without Visual Studio, these comments will be visible to a user opening the source code file (in notepad, for example)

Visual Studio 2008 by default also supports two less-frequently used keywords (UNDONE and UnresolvedMergeConflict) and its actually also entirely possible to create your own so-called task-comment tokens as shown here in the Options dialog from Visual Studio…

The trick with doing this, of course, is that the rest of your development team really needs to make the same change to their own instance of Visual Studio or else any such custom tokens you add won’t appear in the other developers’ task pane ‘auto-magically’.  For this reason, I generally recommend against the creation of custom tokens, but if employed across your entire team they can be of value in limited situations where the defaults just don’t entirely meet your needs.

Choice 2: The Task Pane ‘User Tasks’

The next most common place to put task-related comments is in the ‘User Tasks’ part of the Visual Studio Task Pane.  By selecting ‘User Tasks’ from the combo box in place of ‘Comments’, you can select to display a list of User Tasks instead of just tasks from comments in the Code itself…

Unlike with code-comment-based tasks, as shown in this screenshot User Tasks in the Task List window have the advantage of being able to be ‘crossed-off’ when completed rather than your just erasing them when they are done so a running record of tasks both completed and pending can be maintained over time.

This approach however has a few disadvantages that may not be immediately obvious:

1. These tasks are not located in proximity to the lines of code to which they relate and as such they are perhaps more appropriate for more ‘general’ tasks rather than for tasks that need to relate to a specific line or lines of code
2. The name of these tasks isn’t an accident — they are called User Tasks for a good reason: they are user-specific!  These User Tasks are stored in the solution’s user-options file.  This is a hidden file located in the same folder as the Visual Studio Solution file (.sln) but with a .suo extension (for ‘Solution User Options’).  Any source control system worth its salt has these files excluded from being checked into source control and for good reason: they contain all kinds of user-specific settings that allow the Visual Studio IDE to return to the right workspace on a solution-by-solution basis as you move from solution to solution.  In theory, each user who works on the solution from source control gets the same solution file, but by keeping their workspace layout and other related settings in this separate <solutionfilename>.suo file, everyone gets their own settings to themselves.  Since these tasks are already defined as User Tasks, they are stored in this same .suo file and since everyone on the team gets their own one of these, Visual Studio User Tasks are not really effectively share-able between team members.

This can be either a plus or a minus depending on what you are trying to accomplish, but its worth understanding this limitation: User Tasks in Visual Studio are (usually) only stored on the local PCs harddrive, not in source control so they aren’t versioned, backed up, or any of the other goodies that come with storing things in source control.  Yes, I do grant that its possible to store the .suo files in just about any source control system but its certainly not the norm.

Choice 3: Sticky Notes Visual Studio Add-In

This choice is kind of a blending of the first two: the ability to make a ‘generalized task’ not so tied to a specific line or lines of code but also the ability to store it in source control and share it among the development team on a project.

The Visual Studio 2008 Sticky Notes Add-In provides a simple UI for adding comments on a file-by-file basis from within the IDE that are NOT user-specific…

These notes are stored in the actual Project file (.csproj, .vbproj) and so are routinely checked into source control and are therefor accessible to all members of the development team.

Summary of Choices

The choice of where to store task-based comments really comes down to understanding who the target audience is for a task comment and how you want it persisted/stored/shared.

The following table attempts to summarize these factors for each of the task-commenting approaches mentioned in this post…

Task Entry Type	Applies To	Visibility	Recorded In
In-Line Code Comment via Tokens	One or more lines of code	Team	Source Code File
Visual Studio User Task	Entire Solution	Author Only	Solution User Options (.suo) file
Sticky Notes Add-In	Single Source File	Team	Project File (.csproj/.vbproj)

The bottom line: use any or all of these to keep track of tasks, work-items, notes-to-self, or any other task-related notes as you need but make the choice wisely about which one to use when (and likley there are good situations to use all of these at once on a project).

Happy Coding~!