CodeTour and Visual Studio Code

I've been experimenting with CodeTour, an extension for Visual Studio Code that allows you to annotate code and create a "tour" through a project.

My initial reaction is that this can be an effective education tool. 

But after using it a bit more, I can also see it as a way to document code. It sits somewhere between large comment blocks in the code and having a separate document with details. Lots of things to think about.

CodeTour in Action

If you want to see a CodeTour in action, just install the extension from the Visual Studio Marketplace (CodeTour) and grab this repository from GitHub: ASP.NET MVC Conventions. When you open the repo for the first time, it will ask if you want to run the CodeTour.

Otherwise, you can use the "CodeTour" section in the Visual Studio Code Explorer.

From there, you will be guided through a tour of ASP.NET MVC conventions based on the default template.

You can also expand the tree and jump to specific steps:

Features

There are quite a few features that I used here. 

Annotating a Line of Code

The most basic is to point to a line of code and provide some information about it.

Here we have a pop-up in the middle of the editor that allows you to provide some more information. The content is Markdown, so you can use various types of formatting.

The arrow buttons at the top of the box let you move from step to step (there are keyboard shortcuts for navigating as well).

Annotating a Block of Code

In addition to pointing to a line, you can also annotate a block of code with a highlight.

Shell and Visual Studio Code Commands

Some of the cooler features allow you to put in shell commands to run from the terminal and also commands that run from the Visual Studio Code command palette.

This has a link for "dotnet run" which will execute in the terminal (this starts the web application).

The second link will open a browser to http://localhost:5000. But instead of being just a link (which prompts whether you really want to open it), this uses a Visual Studio Code command to open the URL (so there is no extra prompt).

Here's a clip of both links in action.

Here's what the Markdown looks like:

The shell command is prefixed with ">> ". This will run that command in the terminal.

The bottom line is similar to a standard Markdown link, with the text in square brackets and the target in parentheses. But instead of having "http:", the target has "command:". 

The details for this are in the documentation under "Command links": https://marketplace.visualstudio.com/items?itemName=vsls-contrib.codetour.

As a side note, I used a non-breaking space ( ) in the non-link version of the URL (the line between the clickable bits). This prevents the Markdown interpreter from automatically creating a link out of this.

Content Steps

Another feature I used is a "Content Step". This provides a block of Markdown that is not associated with a specific block of code. I used this for the introductory steps and the summary step.

Directory Steps

Sometimes we want to point at a folder rather than a code file. A "Directory Step", will open up the Visual Studio Code Explorer to a relevant folder, and you can provide annotations for that. In this case, I pointed out several of the ASP.NET folders, including "Controllers", "Views" and "Shared".

Other Features

There are some other features that I haven't used yet. You can check out what's possible in the documentation: https://marketplace.visualstudio.com/items?itemName=vsls-contrib.codetour.

Wrap Up

This is interesting from an education and training perspective. In this case, I was able to take an article (The Secret Code: ASP.NET MVC Conventions) that points to a GitHub repo, and turn it into something more interactive that walks through the repo.

But this is also interesting from a documentation perspective. This could be used as a way to annotate a code base so that when a new developer comes on, they can be led through the relevant points. It can also be seen as in-line documentation for areas where we don't want to pollute our code with large comment blocks, but want something a bit better than a separate document that has all of the relevant information. This can give us an "in between" where the documentation is available with the code, but it is not directly mixed in with the code.

Take a look, and see what you can do with it.

Happy Coding!