Code comments are as common as any language keyword. From the venerable TODO to a DAFUQ, I’ve seen comments used to inform, express frustration, and mark jobs to be done. For a long time finding these comments would frustrate me. Why comment a piece of code with a FIXME when you could just fix it or create an issue in your tool of choice?

While I’m still of the opinion that these comments are troublesome when going stale, I’ve changed my perspective a bit by looking at them as tags that can help me navigate a code base. These tags are hints for me or my team to take a look and action on a part of the code we’ve marked as “of interest”.

After some time accepting and working with these “tags” I started to look for tooling I could use in NVIM that would enhance my experience. I wanted these tags to be visually distinctive and I wanted my IDE/code editor to help me find them. Turns out that a few awesome folks have wanted and built this tooling, and it’s not just for big IDEs.

Let’s start by looking at the tags before we go into the tooling.

Tip

You can jump to the example configuration for VS Code / Codium if that’s all you need.

Tags

There’s a ton of tags that we could use but to keep it “short” I’ve been using some version of

TODO

The “classic” comment that can be found in many a code base.

  • Alternatives: TO-DO

WARN

Used to warn the reader that something is off but can’t be easily identified as a bug or hack.

  • Alternatives: WARNING, WAT

ISSUE

Tag to indicate something is off and we should come back to fix. I also add an issue link if one exists. It’s important to note that this tag should be removed. I think it’s a big smell if a “fixme” comment is there for a long period of time. At that point, do you really need to fix it?

  • Alternatives: BUG, FIX, FIXIT, FIX-IT, FIXME, FIX

HACK

Tag to indicate that a piece of code might be working well but has some sort of smell or is not optimal

TIP

Tag to provide a call out for some insight around the use or structure of a piece of code. Used more to draw attention of the reader than to properly document.

  • Alternatives: IMPORTANT

INFO

Sometimes I want to add some addition context to a piece of code. I treat this tag like a “general” code comment.

  • Alternatives: NOTE

PERF

I rarely use this tag, but once in a while I find I want to call out the structure of a code block as being optimize or needing optimization. I find this helps with code that might not look “normal” or following common patterns but isn’t a HACK (at least in my eyes).

  • Alternatives: OPTIM, PERFORMANCE, OPTIMIZE

TEST

Used to mark a section of code that’s meant to be a test. Imagine having a utility function that you just don’t know if you want to keep

  • Alternatives: TESTING

Tooling

Tooling has always been a rabbit hole for me. I was “lucky” that Lazyvim has todo-comments.nvim already packaged in the distribution.

todo-comments.nvim is another fantastic plugin by folke that

is a lua plugin for Neovim >= 0.8.0 to highlight and search for todo comments like TODO, HACK, BUG in your code base.

This plugin uses other excellent plugins like trouble.nvim, telescope, and fzflua to provide an IDE like experience.

todo-comments

Having the TODOS, WARNINGS, and other tags searchable and show up in trouble.nvim makes using them to navigate the code base incredibly simple. Over the last couple of weeks it’s helped me find code blocks that needed attention. While some of these comments were definitely out of date, I still found them useful. At a minimum I had a really easy time identifying where to do some clean up.

Note

I found the default configuration for todo-comments to be exactly what I needed.

VS Code and VS Codium

While I was perfectly happy in my Lazyvim bubble, for the rest of my team VSCode / VSCodium is the editor of choice. I found two really great extensions that make working with these tags a joy, Todo Tree and Better Comments Next.

Todo Tree will provide a similar experience to trouble and telescope, making the comments searchable and letting you navigate to them with a click.

todo-tree-ui

Better Comments Next provides the color and highlighting for the comments.

To get these extensions to work similar to my NVIM plugins I added some configuration in the .vscode/settings.json file.

Important

You will want to define a minimum set of tags that are shared in all of your IDEs and code editors. It’s fine if one is a superset of the other, but a minimum overlap will help you and your team have the same experience.

Todo Tree

To configure Todo Tree I added two sections

  • todo-tree.general.tags: a list of all the tags I wanted to add/support

    "todo-tree.general.tags": [
    "BUG",
    "HACK",
    "FIX",
    "FIXIT",
    "FIX-IT",
    "FIXME",
    "FIX-ME",
    "IMPORTANT",
    ...
],

  • todo-tree.general.tagGroups: an object that defines how to group the tags into categories. The keys of the objects are the categories while the values can be simple string or arrays of strings.

    "todo-tree.general.tagGroups": {
    "INFO": ["NOTE"],
    "TODO": ["TO-DO", "[ ]", "[X]"],
    "BUG": ["FIX", "FIXIT", "FIX-IT", "FIXME", "FIX-ME"],
    "WARN": ["WARNING", "WAT", "XXX"],
    "HACK": ["IMPORTANT", "TIP"],
    "PERF": ["OPTIM", "PERFORMANCE", "OPTIMIZE"],
    "TEST": ["TESTING"]
}

Better Comments Next

[Better Comments Next][better-commments-next] required a bit more configuration. Just like with Todo Tree, I needed to add a section to the configuration.

  • better-comments.tags: a list of objects that configure the styles of a tag

    "better-comments.tags": [

    {
        "tag": ["todo", "to-do", "[ ]", "[X]"],
        "color": "#2563EB",
        "strikethrough": false,
        "underline": false,
        "backgroundColor": "#39579748",
        "bold": false,
        "italic": false,
        "multiline": true
    },
    {
        "tag": ["note", "info"],
        "color": "#14D1F3FF",
        "strikethrough": false,
        "underline": false,
        "backgroundColor": "#18879B61",
        "bold": false,
        "italic": false,
        "multiline": true
    },
    ...
]

VS Code and VS Codium example

Here’s a complete example showing the current configuration I use in VS Condium. For a breakdown on the extensions that I’m using take a look at VS Code and VS Codium.

{
    "workbench.iconTheme": "material-icon-theme",
    "workbench.sideBar.location": "right",
    "editor.minimap.enabled": false,
    "editor.fontSize": 18,
    "better-comments.tags": [
        {
            "tag": "#",
            "color": "#18b566",
            "strikethrough": false,
            "underline": false,
            "backgroundColor": "transparent",
            "bold": true,
            "italic": false
        },
        {
            "tag": "!",
            "color": "#FF2D00",
            "strikethrough": false,
            "underline": false,
            "backgroundColor": "transparent",
            "bold": false,
            "italic": false
        },
        {
            "tag": "?",
            "color": "#3498DB",
            "strikethrough": false,
            "underline": false,
            "backgroundColor": "transparent",
            "bold": false,
            "italic": false
        },
        {
            "tag": "//",
            "color": "#474747",
            "strikethrough": true,
            "underline": false,
            "backgroundColor": "transparent",
            "bold": false,
            "italic": false
        },
        {
            "tag": ["todo", "to-do", "[ ]", "[X]"],
            "color": "#2563EB",
            "strikethrough": false,
            "underline": false,
            "backgroundColor": "#39579748",
            "bold": false,
            "italic": false,
            "multiline": true
        },
        {
            "tag": ["note", "info"],
            "color": "#14D1F3FF",
            "strikethrough": false,
            "underline": false,
            "backgroundColor": "#18879B61",
            "bold": false,
            "italic": false,
            "multiline": true
        },
        {
            "tag": "*",
            "color": "#98C379",
            "strikethrough": false,
            "underline": false,
            "backgroundColor": "transparent",
            "bold": false,
            "italic": false
        },
        {
            "tag": ["hack", "important"],
            "color": "#9B59B6",
            "strikethrough": false,
            "underline": false,
            "backgroundColor": "#9C59B62B",
            "bold": false,
            "italic": false,
            "multiline": true
        },
        {
            "tag": ["bug", "fixme", "fix-me", "fix", "fixit", "fix-it", "issue"],
            "color": "#DC2626",
            "strikethrough": false,
            "underline": false,
            "backgroundColor": "#B95E5E47",
            "bold": true,
            "italic": false,
            "multiline": true
        },
        {
            "tag": ["perf", "optim", "performance", "optimize"],
            "color": "#FD79A8",
            "strikethrough": false,
            "underline": false,
            "backgroundColor": "#FD79A731",
            "bold": false,
            "italic": false,
            "multiline": true
        },
        {
            "tag": ["warn", "warning", "wat", "xxx"],
            "color": "#FBBF24",
            "strikethrough": false,
            "underline": false,
            "backgroundColor": "#90773860",
            "bold": true,
            "italic": false,
            "multiline": true
        },
        {
            "tag": ["test", "testing"],
            "color": "#FF00FF",
            "strikethrough": false,
            "underline": false,
            "backgroundColor": "#983B9871",
            "bold": false,
            "italic": false,
            "multiline": true
        }
    ],
    "todo-tree.general.tags": [
        "BUG",
        "HACK",
        "FIX",
        "FIXIT",
        "FIX-IT",
        "FIXME",
        "FIX-ME",
        "IMPORTANT",
        "INFO",
        "ISSUE",
        "NOTE",
        "PERF",
        "OPTIM",
        "PERFORMANCE",
        "OPTIMIZE",
        "TEST",
        "TESTING",
        "TIP",
        "TODO",
        "TO-DO",
        "WARN",
        "WARNING",
        "WAT",
        "XXX",
        "[ ]",
        "[x]"
    ],
    "todo-tree.general.tagGroups": {
        "INFO": ["NOTE"],
        "TODO": ["TO-DO", "[ ]", "[X]"],
        "BUG": ["FIX", "FIXIT", "FIX-IT", "FIXME", "FIX-ME"],
        "WARN": ["WARNING", "WAT", "XXX"],
        "HACK": ["IMPORTANT", "TIP"],
        "PERF": ["OPTIM", "PERFORMANCE", "OPTIMIZE"],
        "TEST": ["TESTING"]
    }
}