Visual Studio Comment Shortcuts: Efficiency Tips

By now, we all know Ctrl+C and Ctrl+V like the backs of our hands. Heck, some developers write entire programs using these copy/paste shortcuts! But what about using other shortcuts to make yourself more efficient? That’s right, I’m talking about Visual Studio comment shortcuts.

You may be aware that the Ctrl+K, Ctrl+C chord creates a comment, but there’s a bit more magic to it than the shortcut alone.

This post will delve into some details about context, language, and efficiency when it comes to comments in Visual Studio. If you’re looking for reasons why you should know this, Mark Henke does a nice job explaining four good reasons.

Now, let’s follow tradition by starting with the basics and working our way to more advanced concepts as we go along.

The Basics

The most basic shortcut for creating a comment is Ctrl+K, Ctrl+C. This, of course, is the default shortcut for Edit.CommentSelection, which can be mapped to whatever you’d like. I’m going to stick to defaults, but later in this post, I’ll show you how to change those. And to round it out, the mapping for uncommenting is Ctrl+K, Ctrl+U. Those are the keystrokes. Use them. Practice them. Know them.

Now, Visual Studio knows how to comment in several languages. It can comment in HTML, JavaScript, SQL, C#, CSS—you name it!

The comment shortcut will also lay down comments on a single line or multiple lines. That all depends on what you’ve selected with your cursor.

If you’ve got the cursor on a line with no highlighting, it’ll just comment the line from the start of your code. It doesn’t, however, leave a space between the comment characters and your code; this has been known to upset JS linters that like to see that space by default. I’ll admit, it’s a bit easier on the eyes.

Non-Keyboard Visual Studio Comment Shortcuts

What if you want to comment multiple lines but leave some space before the code? Normally, Ctrl+K, Ctrl+C will leave the comments in a nice column like in the following example:

public class Class1
{
    //public Class1()
    //{
    //}
    //public void SayHelloConsole()
    //{

    //    Console.WriteLine("Hello!");
    //}
}

But notice a few not-so-nice trends in that sample? For one thing, there’s the “missing” comment line with no // and the comment characters are right up against the code. That makes it tough to read.

Here, I’m commenting code, so it’s not that much of a problem. I would eventually either delete that code or remove the comments. But what if it’s a really useful comment?

Perhaps you’ve left an important note to your colleagues or future self explaining some odd block of code. You really want readability in that case! Here’s a somewhat contrived example:

function sayHello() {

    // Say hi using this arrow function
    // I don't generally write JS without semicolons
    // But, apparently it's the new thing
    // I feel either way about it.
    const sayHi = () => 'hi'

    //And for some comments without
    //space after the comment chars
    //it's just not as easy to read!
    console.log('Hello')
    return sayHi
}

It’s a bit easier on the eyes when there’s some space between the comment marks and the content. Usually, you’d use a multi-line comment in cases like this. Unfortunately, Visual Studio will only lay down several single-line comments instead.

Here’s a trick for commenting multiple lines at once with a space, though. First, get out your Alt key and hold that guy down while you use the cursor to “box select” the columns to the left of your code. Press // and voilà! Comments with space for readability. Some screenshots are in order.

This first screenshot shows a blue vertical line where I’ve “Alt-Selected” the space between two columns. This is where I’ll insert more comment characters with a space.

Now, I just type // to turn all those lines into comments.

And now you’ve got comments with a space! If only there was a keyboard shortcut for that. But at least you can map the shortcuts that are available, as we’ll see next.

Mapping Shortcuts

You can map comment commands to a different keyboard shortcut in the Tools > Options menu. Look in Environment > Keyboard and you’ll see the following dialog:

I’ve filtered the commands by typing “Comment” into the text box. The highlighted command shows the chord for the basic comment command. You can change the scheme to something else, like Visual Studio Code. That will remap the command to Ctrl+/ so you don’t have to flub back and forth if you use both IDEs.

You can also remap or apply shortcuts individually, but this can be a bit of a pain unless you save your mappings. You never know when you might have to reinitialize your developer box. That means reinstalling Visual Studio and possibly losing your custom mappings!

Now that we have the mechanics down, what about the more cerebral factors? One thing’s for sure when it comes to comments: your purpose varies depending on your reader. There are internal and external comments.

So far, we’ve focused on the mostly internal comment shortcuts. Let’s compare these to external comments and learn more shortcuts while we’re at it!

Internal Comments vs. External Comments

There are all kinds of code comments out there. Some common types of comments are the header comments, code comments, and XML documentation comments. Also, we put comments on commits, check-ins, code reviews, and on work items in whatever work tracking system we use. Why are there so many places for comments?

Let’s attempt a classification for these comments that’s based on the consumer.

Developers

Code comments are for developers, but even then, there are sub-classifications. Some comments are for internal development and others are for external developers: AKA consumers.

The internal stuff can be a little loose at times. Maybe you’ll see some quippy things like “why did we do it this way?” But often there are notes about pending work like “NEEDFIX:” or “TODO:” comments. The best use of these comments is to explain something out of the ordinary. This is a good place to look for smells by the way. You can view all the “task” comments by typing the shortcut Ctrl+\,T.

The external stuff is often critical for users. So often, I’ve checked these comments for useful information only to be confronted with nothing at all! It’s fairly easy to place a comment on a single method with Visual Studio. Just type /// (”’ for VB) above the method, property, or class, and Visual Studio puts a template-based XML comment block in there for you! All you have to do is fill in some details.

The Team

Now, the comments for the team come in the form of commit comments, review comments, and work item comments. You can see the changes to a file by showing annotations in Visual Studio. The annotations are linked to the check-in, so you’ll see the check-in comment along with each line annotation.

Ctrl+K, Ctrl+M shows line annotations.

Other types of comments include work item comments, which aren’t really accessible in VS.

But Really, It’s All About the Developers

Let’s consider that your consumers—developers—are under pressure to deliver. They’re using some code you created and packaged for their consumption. This code is built to make your consumers more productive. They need to do X with your assembly or API so they don’t have to write their own code to do X. And consider their situation. At the time of development, they have an IDE, your API, and a browser. This is where your documentation comments can really make it or break it.

Assuming your user’s IDE has some IntelliSense-like feature, they’ll see your doc comments as they code. But this isn’t the only way they’ll want to consume these docs. Often, I’ll pop into some documentation via my mobile device just to explore an API. It’s pretty easy to produce online documentation from your doc comments with GhostDoc to make them more accessible.

While we’re at it, let’s make those comments as useful as possible! We developers need to help each other out. In order to do this, put yourself in the shoes of the consumer. Ask yourself some basic questions like

• What would you want to know by way of the documentation?
• Are there any known performance limitations?
• How is the method typically used? Show an example.
• Are there any specific gotchas?
• What other information would you need in there to do your job well?

Think about that as you consider how to automate documentation. And if you’re concerned about all the “green” in your code, there’s a shortcut to collapse regions of code. This is no substitute for keen organization, but it can get a lot of the comments out of the way so you can center up and focus on the code. Ctrl+M, Ctrl+O (collapse all) and Ctrl+M, Ctrl+P (expand all) are two of my favorites!

With that, you have everything you need to automate the documentation!

Documentation Automation

You can use a number of tools to automate your documentation. Most of these tools will derive the documentation from your comments (for C# methods, ///). And some of these tools even help you start those comments. From there, it’s up to you through good design and good documentation practices to deliver quality documentation to your customer.

Let’s look at some of GhostDoc’s shortcuts that make it even easier.

GhostDoc comes in both free (community) and paid versions (pro and enterprise). Besides producing the documentation, GhostDoc will place boilerplate doc-comments in your code for you.

Just use Ctrl+Shift+D to start documenting your code!

From there, all you have to do is fill in the useful details. This beats going through each method and pressing /// or ”’ for each one.

There’s also a nice spellcheck feature in the pro version that helps keep you honest! I’ve fat-fingered method names enough times to cause embarrassment!

There’s one last shortcut (this is a menu shortcut) I have to mention about GhostDoc Pro. By the click of a mouse, it adds an exceptional header comment to the file! This includes a lot of nice information about when it was last modified and by whom, along with a starter for additional comments on the file itself. You’ve got to see that for yourself if you’re not using it yet!

Put a Bow On It

Basically, what you want to do with your documentation is put a bow on it. It’s one thing to “check the boxes,” but if you really want to help out your fellow developers, you’ve got to do a bit more. Use the tools to support your craft. Think about it this way: a blacksmith uses a hammer to pound metal into shape, but they use their talents to craft something amazing and/or useful!

Commenting code is the part of your craft that’s visible to your consumers (both internal and external). The parts that require your skill and attention cannot be automated, but you sure as heck can automate the rest! Ctrl+End.

Learn how GhostDoc can help to simplify your XML Comments, produce and maintain quality help documentation.

About the author

Phil Vuollet

Contributing Author

Phil Vuollet uses software to automate process to improve efficiency and repeatability. He writes about topics relevant to technology and business, occasionally gives talks on the same topics, and is a family man who enjoys playing soccer and board games with his children.

This author does not have any more posts.