Comments are gray and it's weird!

Most code editors ship with its own color scheme. Basically all editors also allow you to change out the color scheme, and many people do. If we look at the most popular schemes, one commonality between almost all of them is that the color of code comments has low contrast with the background.

According to the WebAIM contrast cheker, for "normal text" you need a contrast of 4.5 for AA and 7.0 for AAA. Let's see how common editors and their commonly used color schemes fare.

Neovim

Neovim 0.10 shipped a new default color scheme. I've pulled the colors from my own neovim (ran without a config) in iterm2; it looks like this:

Foreground (13.99) // Background (6.74)

lazy.nvim is a popoular "get started" collection of plugins, and it comes with a color scheme that looks like this:

Foreground (10.26) // Background (3.11)

One more: one of the top trending colorschemes on dotfyle is material.nvim. It comes in five variants:

Oceanic:

Foreground (6.60) // Background (2.33)

Deep Ocean:

Foreground (8.43) // Background (2.17)

Palenight:

Foreground (6.11) // Background (2.76)

Ligher:

Foreground (5.17) // Background (1.83)

Darker:

Foreground (8.45) // Background (2.03)

Visual Studio Code

VS Code is an extremely popular editor with a bunch of color schemes. Here's some of the built-in ones that have many variations, and two well known ones:

2017 Dark (default):

Foreground (9.96) // Background (4.65)

(Community) Material Theme

Foreground (12.80) // Background (2.44)

Monokai

Foreground (13.95) // Background (3.95)

Solarized Dark:

Foreground (4.08) // Background (2.79)

I'll throw in another scheme that's not built-in, but that I've used, namely Nord:

Foreground (9.25) // Background (2.43)

Cursor

Cursor is the new cool LLM based editor. It's front-page conists mostly of light color schemes, but on /features there's images of a dark scheme as well. It looks like this:

Foreground (12.03) // Background (3.28)

Zed

Zed is another new editor with focus on collaboration features. Whether comments counts as collaboration remains to be seen:

Foreground (6.58) // Background (2.32)

Myself

Here's the color scheme I use on this site, with contrasts in dark/light respectively:

Foreground (21.00 / 21.00) // Background (17.35 / 4.59)

This isn't 100% exactly what I have in my terminal; my background is the same as the (dark mode) background of this site, and my white is slightly weaker:

Foreground (18.26) // Background (16.02)

Summary

Comment contrast range from 6.74 (Neovim default) down to 1.83 (Material.nvim lighter). Only two schemes, Neovim default and VS code's 2017 Dark is AA. Compared to the color used for "normal" code, basically all contrasts are AA.

About Comments

Now that we know comments have bad contrast in most color schemes, let's think about why we care.

The main advantage of higher contrast is readability.

But readability is subjective, right? Yes, however, we have contrast ratings so that designers and developers has a fixed bar to pass for human readability of text. If you are coloring "normal text" and the contrast is larger than 4.5, you have passed the bar, and the text will be readable by very many. In the case of brevity, let's just call this readable. Only three of the schemes above have a AA contrast for comments (and one of them is mine!). The bar is not passed, and so we cannot claim that these comments are readable.

Comments are often prose, and as such, the most similar to "normal text" as anything you can find in a source file. This is different than anything else in there, so the contrast requirement for most of the other tokens does not need to be as high. Even a token you can barely make out gives you information about what that token is, because it's color (and contrast), as well as it's position relative to surrounding tokens, is recognizable: you don't need to check if a line ends with a { or a } when the next line is indented farther than the current line; a gray blur suffices, because you know it's a {.

Comments are not like this! Comments are meant to be read, and your color scheme should help you doing that.

Having weak contrast for comments make them stand out less, and will make them harder to notice. In turn, this will increase the chance of not reading them, them becoming outdated, or never written in the first place. If you don't read existing comments, how likely are you to write new ones?

A comment is a great place for things in your program that you cannot express in the code. Omitting this information is neglecting to share it with your collaborators, both existing and current.

Thanks for reading.

This work is licensed under a Creative Commons Attribution-ShareAlike 4.0 International License