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!

Video: A Tour of Go for the C# Developer

I've found a lot of interesting features and ideas in Go (golang). By exploring these, I've got several things to try out in my primary language (which is currently C#).

If you're curious about Go, I've put together a tour of the language targeted at the C# developer. By building an application that makes concurrent service calls, we can see some of the similarities and differences between C# and Go.

Watch it on YouTube: A Tour of Go (golang) for the C# Developer

There's also a repo with all of the code: https://github.com/jeremybytes/video-go-for-csharp-dev

Features

Here are a few of the things I find interesting about Go:

Opinionated Syntax
Go syntax is C-like, but it has some strong opinions. For example, opening curly braces must always go on the same line as the function (or "if", or other block statement). In addition, the curly braces are never optional for an "if" statement, regardless of how many lines are part of the body.

No Unused Variables
Go does not allow for unused variables. If you declare a variable and do no use it, you get a compiler error. I like this idea since it gets rid of code that isn't used. This also encourages the use of the "blank identifier" (an underscore) which acts as a discard.

Baked-in Concurrency
Concurrency is baked right into the Go language -- in fact, they are called "goroutines" and you use "go" to start one. Channels can be used to communicate between a goroutine and other functions. Seeing how they work makes the idea of Channels in C# (added in .NET Core 3.0) a bit more interesting to explore.

Deferred Calls
Go has a "defer" statement. For example, "defer channel.Close()" will call the "Close()" method at the end of the function (however it exits). This is similar to a "finally" in C#, but it can be used anywhere in a function or method.

Error Handling
Go encourages the the use of "error" instead of exception (which is called "panic" in Go). An error is really just a message. A common pattern is for a function to return a data item plus an error. If the error is populated, then something went wrong. The idea is that we treat errors as messages to be handled in our own code rather than something to be handled by the language or framework. (And "panic" does exist if we have a truly panic-inducing circumstance.)

Multiple Return Values
As mentioned above, it's common for a function to return a data item plus an error. Go supports multiple return values. So we can return multiple values without dealing with explicit tuples.

Interfaces
Interfaces in Go are explicitly declared but implicitly implemented. Meaning, if we have an interface that declares a "String()" method, a type can implement that the interface by simply providing a "String()" method. It does not need to specifically say it implements the interface, it just needs to provide the members. This encourages a different way of using defining and using interfaces. I wrote a bit about my initial experiences here: Go and Interfaces.

Check Out the Video

In building a small application (about 100 lines), the video looks at all of these features, plus a few more. Be sure to check it out:

Happy Coding!