The most popular IDE – VS Code – comes with a ton of extensions, and each can make life easier, more productive and more fun for developers. Recently I came across the Code Tours extension. An extension that supports the creation of guided tours through the files in your VS Code workspace.
A Code Tour consists of a series of descriptive steps – defined using markdown with rich formatting including code snippets, URL references, file links and images – and associated with specific locations in your sources.
A tour can guide a fellow developer through the sources much better and more pleasantly than any readme document could ever do. Using Code Tours, you can create very accessible:
- explanations of involved flows through the code
- analysis of bugs to be resolved
- overviews of the changes created as part of a PR
- descriptions of dependencies between multiple files
- reading instructions across multiple sections in multiple documents
- overviews of solution designs for new features and user stories
- hands on instructions for a workshop or training
To get going with Code Tours:
- Install the Code Tours extension in VS Code
- Start recording a new Tour (for the current project)
- Add Code Tour Steps in the relevant locations in your sources
The code tour is defined in a JSON document included in the project. You can edit that JSON document. It is included with the sources when the files are pushed to a Git repo. The Code Tour can also be exported and imported in a different VS Code instance – to allow sharing without having to push to a repo. - You can start your tour through a code base from the Code Tour pane and from any Code Tour Point of Interest in the code base
Here is an example of a code step that uses from of the layout options:
Using vscode.dev it is easy to share an example of a code base with some Code Tours. Navigate to this URL https://vscode.dev/github.com/lucasjellema/cloudnative-on-oci-2021 that is composed of vscode.dev and the URL for a GitHub repository. What this URL will do is launch vscode.dev (Visual Code in the browser) and load the code in that repository.
If you open the CodeTour pane, you will encounter several Code Tours. Run them to see the effected of being taken by the hand and shown around a code base.
Resources
VS Code Tours Extension https://github.com/microsoft/codetour
YouTube – VS Code tips — The CodeTour extension – https://www.youtube.com/watch?v=cUoYQKZPZcg
Tobias Timm – On board your code base with CodeTour – https://dev.to/tobiastimm/onboard-your-codebase-with-codetour-2jc8
My GitHub Repository with a Tour Guided Code Base: https://github.com/lucasjellema/cloudnative-on-oci-2021
Inspect that same code base in browser based VS Code : https://vscode.dev/github.com/lucasjellema/cloudnative-on-oci-2021
