Comments for metadata and custom code in steroids with Codetour

Introduction

CodeTour is an open-source plugin developed by Microsoft for VS Code that I discarded some time ago, but now I revisited and I am very happy to share my new feelings about it in this article.

No need to mention that I neither work for MS and not sponsored in any way by anyone, just in case.

CodeTour can be very useful for Salesforce developers and architects who work with Apex and Web Components.

Using CodeTour is easy: you basically select a folder, or a file, or a code snippet and write markdown explaining what it is, what is needed for or why is dangerous to touch it 😉 . This is called a step, and a collection of steps makes a tour.

It is important to say that these steps are interactive, which means that the user can follow along with the tour and interact with the codebase as they go.

You can link to external sources, other steps, and has a quite a lot of niceties, that for me are convenient but not key to this article.

The information you enter is saved in clear text files that are modifiable, easy to inspect, and can be committed to Git without impacting the codebase.

Why is CodeTour useful?

I am sure you have faced the situation:

• You arrive to a Salesforce project and someone try to explain you the custom codebase of Apex (with or without frameworks), LWCs, Visualforce pages, etc.
• In the best situation, the code is well structured and commented and even you might be super lucky to have an old and outdated confluence page that explains roughly what it was the architecture a months ago.

But thinking deeper, have a very poluted code footprint with long headers, long changelogs and i = i +1 //increasing i type of comments is not better neither.

What if developers could inside Vscode add some rich formatted comments, explanations and even onboarding tours for new mates without poluting the code? Well, Codetour can do it.

CodeTour can be useful for a variety of reasons, including:

1. Onboarding new team members: providing an interactive guided tour through the codebase, new team members can quickly get up to speed on the project’s architecture, best practices, and coding standards
2. Sharing knowledge: creating tours that explain complex code or demonstrate best practices
3. Back in time code reviews: creating tours that explain code changes, developers can help their team members understand why certain changes were made and how they fit into the larger codebase.
4. Collaboration: creating tours that demonstrate how different parts of the codebase interact together.

In the following screenshots:

• You can see 2 tours (in the first screenshot marked with 1 and 2 in red), one from the Salesforce team for recipes and another one that I created for the project-scratch-def.json file.
• In my tour, there are 2 steps, one for the file and one for a concrete line (red arrows in the first screenshot).
• When anyone starts tour, the first step (2nd screenshot) provides a nice simple markdown explanation on some field explanations what for a newbie to the project can make the difference on understanding the capabilities we are providing when creating a new scratch org.

I didn’t choose this file in the images above unintentionally, this file is a JSON file, which is not comment friendly, but with CodeTour I can easily add comments (codetour and steps) to it.

…but this is old, why are you bringing this up?

Well, you are right, the team inside Salesforce uses it for long time and I reviewed this plugin long time ago, but I discarded because it had a huge weakness for me: the snippets attached to a line didn’t move with the line when the code was updated.

But it has recently received an update that makes it even more useful. A new capability called «pattern» allows you to attach a comment to a regular expression, which means that the comment moves with the code when it is modified. This feature overcomes the issue of misplaced comments that previously prevented me from adopting CodeTour.

In conclusion, CodeTour can be an excellent tool for Salesforce developers and architects who want to comment on their codebases without polluting them and leaving inside Vscode.

With its easy-to-use interface and interactive tours, CodeTour can improve collaboration, promote having updated comments (some developers will never comment anything of course), and onboard new team members quicker and efficiently.

Is this only for custom code?

Not, in fact, I see that we can all benefit from documenting and explaining metadata in a richer way.

I can imagine explaining in detail why a formula looks very tricky but in fact is not, why a sharing rule is the way it is and explaining why permission needs to be in one concrete Permission set.

In fact, when you generalize the concept, Codetour can be used in any text file, regardless of its content.

So, is Codetour the perfect solution?

Not at all, my current biggest nuisances:

1. Not multiline support but rather \n\n is required in a single line makes long comments hard to maintain
2. Not having tags to have a better marking solution could also improve the developer experience and the maintanbility

Links

• https://marketplace.visualstudio.com/items?itemName=vsls-contrib.codetour
• Youtube video tour of codetour 😉 : https://youtu.be/c2J_o7ZkBbM

I hope its useful.