A Journey through your Code
Tags: onboarding, vscode, productivity, codenewbie
Published: 2020-11-17 14:11:26

Do you know the struggle of onboarding new devs to your codebase? Can you recall again what the most critical files were and the reason for feature x y z?

Documentation is challenging, and also most of the developers don't like writing it. Especially when you onboard new fellows, you will feel the pain of lacking documentation.

Do not worry anymore! [`CodeTour`](https://marketplace.visualstudio.com/items?itemName=vsls-contrib.codetour) to the rescue! 👩‍🚒

> VS Code extension that allows you to record and playback guided tours of codebases directly within
> the editor

Basically, with this extension, you can explain your code intents, mark important places, and create
FAQs within vscode that every one of your team can use as a source of information.

The only downside, it is limited to Visual Studio Code at the moment.

## Get started with CodeTour

To get started, open vscode, select extensions and search for `CodeTour.` You can also install it via the [marketplace page](https://marketplace.visualstudio.com/items?itemName=vsls-contrib.codetour).

After installation, open the command palette and search for `Record Tour.`![Command Palette](https://dev-to-uploads.s3.amazonaws.com/i/p9ro3qlbtxh9faicvee2.png)

The next step is giving the recording a name.

![Naming the record](https://dev-to-uploads.s3.amazonaws.com/i/3quvqvfy6p58iat4h50t.png)

You can associate a `CodeTour` to a specific commit, tag, or branch. To keep it simple, we will go with `None`. ![Branch selection](https://dev-to-uploads.s3.amazonaws.com/i/cqlxrzb3wxhof9e6tw6u.png)

You can see in the bottom left corner of your screen a `CodeTour` section now.

![CodeTour section](https://dev-to-uploads.s3.amazonaws.com/i/86vaid7t95j1utkq40t6.png)

## Recording our first Tour

To add your first step, navigate to any code-file you want to explain and press the `+` within the editor's left gutter.

![Plus sign](https://dev-to-uploads.s3.amazonaws.com/i/w7pcm5sb7pdgtx46c056.png)

Within the discussion panel, you can explain your intent or add some useful information and hints for your team's other developers.

The editor supports markdown, which is excellent!

![Discussion First Step](https://dev-to-uploads.s3.amazonaws.com/i/m39gj9ypn1xtdvop70ae.png)

Press the `Add Step to Tour` button to continue.

That's it! You have successfully created the first step to your new Tour.

![The first Step created](https://dev-to-uploads.s3.amazonaws.com/i/06bflvj4tbl3hotfoy0k.png)

To expand your first `CodeTour`, you could add several more steps, navigate between more files, and mark the important stuff.

You could even export the tour file and commit them alongside your codebase.

## CodeTour vs. Comments

I like the idea of having tours within my source code to onboard people or explain a bit more in-depth about what I was thinking.

I don't think that they are a proper replacement for code comments or refactoring the code with clear intentions.

Also, this extension is exclusively available for vscode yet. This makes it pretty unusable for everyone working outside of Visual Studio Code.

CodeTours, Documentation, Comments, and the right intentions visualized by your code should all live happily in peace together within your codebase.

## Conclusion

If you want to bring your onboarding or feature explaining to the next level, `CodeTour` is an excellent supporter for that job 😉.