Typechecked... Comments!?

That's right, you might be familiar with a type system in computer programming, but have you ever considered applying it to comments?
This post introduces Code Couplet, a new VS Code extension which does exactly that.

Manually Pinned Comments

First, a short bit of background on types. Skip this paragraph if you already know what they are. We program computers with code, written as text. For example, print('hello') defines a line of Python code that will output "hello". Code also defines variables; for example a = [1, 2, 3] makes the variable a a list of three numbers. (Statically) Typed languages impose an additional restriction: every variable must have a fixed type. So you might have to write a: number[] = [1, 2, 3] to tell the computer it will be a list of numbers. The advantage of these extra words is that future you can be certain that when you want to look at the value of a, it will be a list of numbers. The system which guarantees this fact is called the typechecker.

What are typechecked comments? (and why?)

Now I'll explain what I mean by typechecked comments. Just like the typechecker ensures correspondence between variable construction and usage, Code Couplet keeps track of comments and the code they refer to. If you change code or comments that we're tracking, we will throw an error in the editor, in the same way a type checker would.

Up until this point I've explained a bit about what the idea is, but I haven't gone into why do this in the first place. Computer code itself tells the computer what to do. Comments within the code explain to humans why or how the code does what it does.

The problem is that the comment only makes sense if the code it was written for is still there!

In the worst case, an outdated comment will give you a completely misguided assumption about the behavior of the program. This happens because nothing ensures that the comment and code match. If in future work, you change this code's behavior to fix some issue, the only compulsion to update the comment comes from your own attention in noticing it. The goal of this extension is preventative care: a tiny amount of up-front effort will save plenty of headaches down the road.

How does it work?

Two commands serve as the entry point to the extension in VS Code:

• Auto-Pin Lines: This is the simplest command, but it can only be used on a block of lines with the following structure: full-line comments followed by code. First, select such a block. Then run the command; it will commit this link and highlight the saved region, as shown below.

Automatically Pinning Comments

• Manual Pin Lines: This command gives the most flexibility, but it operates in two parts. First, select a comment (or any text, really) and run the command. Then, select the code and run the command again. The advantage of this flexibility is that you can be very specific about what relationship to track. For example, maybe the comment explains something about timeout in 60 seconds, so you specifically link the number 60 between the comment and the code. This feature also lets you make links across different files.

Once you have used one of these commands to create a link between a comment and its code, they will be highlighted in the editor. Blue for the code, green for the comment. These links are stored at the root of your repository, in a folder called .code-couplet. The expectation is that you also commit this to version control, so that your fellow developers or future self can also maintain these pinned comments! From this point on, the extension will emit a diagnostic error for any text in the source file that does not match the committed value.

The cleverest thing this extension does should also be the most invisible: it automatically updates committed positions as you edit the file. That's necessary because positions are saved as line and column numbers, so if you were to add a single line at the top of the file, every pin in the file would be marked wrong! That really wouldn't be an enjoyable experience. Instead, we track changes in the same way VS Code itself does for breakpoint position updating.

Future Plans

The funny thing about this project is that it's been sitting on my computer in a completed state for at least the last 3 months, so it's only after using it for quite a while that I'm sharing it publicly.

Currently the program is implemented as a VS Code extension (because that's what I use), but if it's useful to others it would be possible to extend to any other editor through the Language Server Protocol.

The most immediate plan is to expose the validation feature through a separate command line binary, so that for example you could hook comment-code checking into your build process, pre-commit script, or continuous integration setup.