Comments in code might not only be some text floating around the functions, variables and classes, but they might contain some extra semantic information. With this improvement, you can navigate through projects much faster or even organize your knowledge. In this blog post, I’ll show you two ways on how to add extra metadata to comments in Visual Studio.

Intro

Navigating through a large codebase might be a complicated task. It might be especially an issue when you have big projects (not to mention legacy systems) where logical parts are spread across many different files.

In Visual Studio offers many tools that help with moving between headers, declarations, class hierarchies or all references of a given symbol. But what if you’d like to put a “todo” item? Or some extra note? Such supplementary information can not only help with quick tasks but also might build knowledge about a system.

Here are the things you might want to use to help in Visual Studio

• Task List
• Hashtags (as an extra plugin)

Let’s start with the first one.

Task Lists

Visual Studio contains a feature that enables us to add metadata directly in comments; It’s called Task List. Take a look at this piece of code from my legacy project:

class ShaderProgram
{
private:
    GLuint mId;
    std::vector<Shader *> mShaders; // refactor: 
                                    // convert to 
                                    // smart pointers!
public:
    // todo: implement other special member functions!
    ShaderProgram();
    ~ShaderProgram();

As you can see above, I put keywords like refactor: or todo: inside comments.

Visual Studio builds an index of all comments with those special keywords and shows them in a separate window:

This is a handy way of managing simple activities or just taking some small notes for the future. What’s more, the refactor keyword is a custom marker. Visual Studio adds flexibility to set it in the environment settings.

Here’s the link to the documentation Use the Task List – Visual Studio | Microsoft Docs

The task list is a nice improvement! The metadata lives inside comments so that other developers can pick up the same information. Still, you cannot easily transfer custom keywords, and the task window offers only basic support. For example, it doesn’t group things (like grouping all of the to-do lines).

Is there anything better?

Hashtags in Visual Assist

For several years I’ve been a happy user of Visual Assist – which is an excellent tool for enhancing various aspects of Visual Studio (have a look at my previous blog posts here or here). The tool also has a powerful feature called Hashtags. This is a combination of named bookmarks, task list and tags that you might know from social networks.

Take a look at the example from my project with extra notes:

/// creates and can build GLSL programs, #shadersSystem
class ShaderProgram
{
private:
    GLuint mId;
    std::vector<Shader *> mShaders; // #refactor
                                    // convert to 
                                    // smart pointers 
public:
    // #refactor #ruleOfZero implement 
    // other special member functions!
    ShaderProgram();
    ~ShaderProgram();

As you can see, this is just regular source code, but please notice those words proceeded with #. I’m using them to mark places that might be worth refactoring. For example, notes about refactoring:

std::vector<Shader *> mShaders; // #refactor 
                                // convert to smart pointers

Or another example:

/// creates and can build GLSL programs, #shadersSystem

This time I’ve used #shadersSystem which groups elements that are crucial to the handling of OpenGL Shaders in my animation application.

Below you can see all of the tags that are displayed in the VA Hashtags window. Similarly to Visual Studio, Visual Assist scans the source code and presents the indexed data.

In the picture above, you can see lots of different tags that I put throughout the code, for example:

• #GlutCallbacks – they refer to all callbacks that I passed to the GLUT framework (for my OpenGL Windows Application). With all of the tags grouped under one item, I can quickly move between those functions.
• #refactoror #modernize – things to improve later.
• Other “notes” that refer to some subsystems like #uiTweaks, #mainLoop and others.

The screenshot also shows a considerable difference compared to the task window. The hashtags are grouped, you can also filter them, or hide according to the project name, directory or even a filename.

Tags are created “on the fly”, there’s no need to predefine them in some configuration window. You just type # and some extra text (you can configure the minimum length of a tag, it’s 3 by default).

Tags are stored directly in the source code, so other developers can immediately see the same information (assuming they also use Visual Assist). Such functionality can be used to create even some simple task manager when you can assign a task by the name of a developer:

// #bartekToDo: please improve this code! don't use goto!

Here are some more things you can do with them

• Cross-reference other tags. You can write see:#otherTag and Visual Assist will build an extra list per tag that you can check.
• When you type # Visual Assist with autocomplete tags, so you can easily refer to existing hashtags
• When you hover over a hashtag in the hashtags window, you’ll see a tooltip with the source code that’s near the tag; this allows to get a better orientation without actually moving to the code.
• And many more!

Here’s a great video that summarises the tool:

Summary

In this short blog post, I wanted to describe two tools that you can use to add extra information to comments. Having little todo: comments or additional notes can enhance your daily work and build a handy list of actions for the future, or even build up the knowledge about the system.

Depending on your preferences, you can keep those extra notes permanently in your code or just temporarily and gradually move the knowledge and todo actions into external documentation or task manager.

In my daily work, I prefer VA hashtags over regular bookmarks, as they are easier to use in most cases and shows that extra information and structure. You can read more about VA Hashtags on their documentation page: Visual Assist Hashtags.

Back to you

• Do you use some extra tools that help you with code navigation?
• Do you use Visual Studio task window and task comments?
• Have you tried VA hashtags?

This blog was brought to you by Bartlomiej Filipek, you can check out his C++ blog at bfilipek.com

Microsoft Visual Studio 2019 moved all extension menus, including the VAssistX menu of Visual Assist, to a new, top-level Extensions menu. According to Mads Kristensen, a Senior Program Manager at Microsoft, the menus were moved to “give the ecosystem more prominence and declutter the top-level menu when you have a lot of extensions installed“. That reasoning might be solid, but it does require an extra keystroke or click to reach extension commands.

In prior versions of Visual Studio, the VAssistX menu is opened via a single Alt+X. That shortcut, fortuitously, now opens the Extensions menu. In Visual Studio 2019, a subsequent X opens the VAssistX menu within the Extensions menu.

If you are a keyboard user of Visual Studio 2019, use Alt+X, X to reach any VAssistX command previously reached with Alt+X. And when you in the documentation for Visual Assist, know that you must use Alt+X, X every time you read Alt+X.

Those looking to restore old behavior in Visual Studio 2019 might find Extensions in Main menu useful. If you try the extension and want a single Alt+X to open VAssistX, use ‘Tools | Customize |Commands’ to change the accelerator key for Extensions, e.g. from &x to &i.

Microsoft tightened security in the Windows 10 Version 1709 Fall Creators Update (FCU), but unfortunately, the tightening adversely affects the performance of applications that use the Win32 GetPixel API. Visual Assist is one such application so initial opening of editor windows in Visual Studio, when Visual Assist is active, can be extremely slow.

You can speed up the opening of edtor windows when using Visual Assist to pre-FCU levels by disabling Control Flow Guard for Visual Studio. Navigate to:

Windows Defender Security Center | App & browser control | Exploit protection settings | Program settings | Add program to customize | Add by program name

Be cautious and choose the exact file path(s) for Visual Studio, or disable protection for any application named “devenv.exe”.

Scroll to disable Control Flow Guard (CFG).

You might improve the performance other aspects of Visual Assist in Visual Studio, at least with respect to the effects of tighter security in the FCU, by disabling all 21 program security settings specific to the application.

Apply, and restart your PC.

You can improve performance of all affected applications in the FCU by disabling CFG at the system level:

App & browser control | Exploit protection settings | System Settings

Obviously, disabling a security feature has its own cost, i.e. less security. You can learn more about the slowness of the API at TenForums and in the Visual Studio Developer Community.

Many of the dialogs and drop-downs of Visual Assist allow efficient lookups via filtering. For example, filtering within Open File in Solution—a dialog with all files in a solution—lets one find a file quickly if only portions of a name are known. This means one can find veryLongFilenameInProjectTomato.cpp if he knows only “long” and “toma”.

Filtering takes many shapes. Aside from substrings, one can filter using simple expressions. Our expression syntax isn’t full regex but it is tailored to the content being searched.

In this blog post, I introduce searching using logical “or”.

Filtering using logical “or” is often applicable when searching VA Hashtags, where tags are created on-the-fly and often without standards. For example, developers might annotate code with VA Hashtags of the format “todo” followed by the name of the teammate who needs to review or fix the code, but names are entered as first names, last names, or misspelled variants thereof.

For tasks related to developer John Smith, we might find VA Hashtags in either of the following forms.

// #todoJohnSmith
// #todoJSmith

Filtering for “smith” in the VA Hashtags tool window easily finds both.

But a teammate might annotate code with only John’s first name.

// #todoJohn


In this case, filtering for “smith” won’t find the new hashtag. We need to search for “smith or john”, and we use a comma in our expression to do that.

Then, our code might also include unrelated hashtags for John, e.g., a comment directed only at him.

// #John, I fixed this for you.

The previous filtering for “smith or john” will include the unwanted entry.

To omit the unwanted entry, we need to search for “todo and smith” or “todo and John”. We do that with multiple substrings and a comma.

This final expression using logical “or” gives us exactly what we want.

You can use expressions in all dialogs and drop-downs that support filtering, including the several that support logical “or”:

• Open File in Solution
• List Methods in File
• VA Hashtags

If you want to know more about expressions, study one of the features that supports logical “or”, then experiment in all the dialogs and drop-downs you encounter.

Logical “or” requires Visual Assist build 2062 or newer.

If you use Visual Assist, you are probably familiar with its Quick Refactoring Menu—available via a hovering icon or the default shortcut (Shift+Alt+Q). But, you might not appreciate how frequently the menu is available. Quick Action Menu is a more apt name.

Availability aside, the Quick Refactoring Menu is an efficient method of tapping into the features of Visual Assist because the menu contains only pertinent actions; it’s always concise. (If you examine the “Refactor (VA)” submenu of the editor’s context menu, you will find all possible actions. The entries enabled in any one scenario are the ones in the Quick Refactoring Menu.)

Available actions in the Quick Refactoring Menu depend on what Visual Assist thinks you might do and where you are: in whitespace, in a symbol, or with a selection.

Browse the following list of actions that can appear in the Quick Refactoring Menu. Look for unfamiliar actions and envision scenarios in which they make sense. Try a few and add them to your arsenal. If you can’t fathom when or where an action might be available, click through and find an answer in documentation.

If you have ever been frustrated by an inadvertent zoom-in or zoom-out in Visual Studio, you probably know there is no convenient way in the IDE to reset the zoom level to 100%. Instead, the IDE requires you to “reset” via increments until you reach 100%.

These inadvertent zooms occurred often enough among the developers of Visual Assist that one of them created a more efficient way to reset. You can have access to the functionality by assigning a shortcut to VAssistX.ResetEditorZoom. Use Ctrl+0 if you want to be consistent with the reset commands in web browsers.

VAssistX.ResetEditorZoom works only within the scope of the text editor, and you assign a shortcut in the usual manner–via the options dialog of the IDE.