Let's Write Beautiful CSS Comments

Your code isn’t as self-explanatory as you think it is. Every line you write makes more sense to you than it does to anybody else on your team. And given enough time, even you will forget how your stuff works. This is doubly true for CSS. Think about it: you can’t really break down your CSS into tons of little descriptive functions the way you can with JavaScript or Ruby. Breaking declaration blocks into tiny, reusable classes doesn’t pack the same descriptive punch as good function names. Self-documenting CSS isn’t a thing.

There’s often loads of intention behind why styles should be applied to a given element, but those ideas get lost in translation as we write CSS. Human intention rarely shines through those cold, hard selectors, properties, and values. This is one of the reasons it’s so notoriously difficult to maintain other people’s CSS, and it really stifles collaboration. Fortunately, it can be remedied with the use of comments. Writing high-quality comments gives us a way to communicate intention to our teammates. If we comment beautifully, we work together beautifully. This post is about those beautiful comments.

Beautiful Comments Are Plentiful

First thing’s first: you don’t write enough comments. It’s the truth. I realize it’s not fun to hear. I’m sorry. But please write more comments. If you don’t comment your CSS, you’ll confuse other people looking at your code, and, more embarrassingly, you’ll confuse future you. If you do comment CSS, everybody will be less confused, and things will be accidentally broken less often. You will be popular and generally well-liked, and people will remember to send you cards on your birthday. Comment more.

Knowing when and what to comment can be tricky, so here are a couple rules of thumb to help you comment more frequently and usefully:

• Always document hacky code. If you find a tricky solution for something on Stack Overflow, be sure to describe what you were fixing, and include the URL to give context to future developers.

• Always document clever code. If you find a non-obvious way to do something, be sure to include a clearly-worded comment to describe what’s happening. (You should avoid writing clever code if possible, but it’s sometimes a necessary evil.)

• Always document magic numbers. Add a comment to make your magic numbers easy to find and understand for when they (inevitably) break. A good magician never reveals his or her secrets, but a good developer always does.

• Always document related styles. Ideally, all the moving parts in your code can work independently from each other, but we live in a fallen world where this isn’t reality. If you write any rules that are affected by external elements, write a comment to note this relationship. One example of this is adding a position: relative rule to a parent that contains a position: absolute ancestor.

• Always comment obscure properties, values, or selectors. I’m looking at you, -webkit-overflow-scrolling: touch and backface-visibility: hidden. Just because you know what a little-known property means doesn’t mean that everybody looking at your code will.

• Turn code review discussion into comments. If your workflow involves code reviews, any time a question is asked about how or why something is done, turn the answer into a comment. If something is worth asking a question about, it’s worth commenting.

While this certainly isn’t a comprehensive list, if you follow these rules, you’ll be well on your way to having plentiful comments. Stay vigilant for these things as you write and review code.

Beautiful Comments Say Why (Not What)

/* BOGUS */
input:checked {
  /* Adds a 5px border to bottom of this element */
  border-bottom: 5px solid green;
}

/* BEAUTIFUL */
input:checked {
  /* Adds "selected" indicator to this element */
  border-bottom: 5px solid green;
}

This example shows two potential comments for one line of code. The first one is very literal and states the obvious. Not useful. The second one is more useful and describes what the code is intending to do. Maybe a little contrived, but much more useful.

It’s more useful to state what code is intending to accomplish rather than what exactly it’s doing. Focus on the why, not the what. When you’re describing intention, you’re creating a teeny-tiny bit of abstraction, which gives you the freedom to change the related code. In the above example, the 5px can be changed to 0.2em, and the comment is still relevant.

Notice how the “bogus” comment is mentioning an explicit value inside the comment? Whenever you see this, a red flag should go off in your head. It’s usually a good idea to avoid that. It’s a sign you’re describing the what. If the value changes, the comment will need to change as well. It also introduces the possibility that the comment won’t get updated, which is sure to cause confusion. Incorrect comments are even worse than no comments at all.

Describing the why also lets you swap out the what if need be. Need to implement the above “selected” state using a :before pseudo element instead of a border? No prob. Go for it. You don’t even need to touch the comment.

Additionally, these types of comments serve as a signpost, justifying why code was written in the first place. This is handy if you’re refactoring code and need to know what a chunk of code is doing. It’ll help answer the question, “If I remove this, will anything break?”

Beautiful Comments Are Aesthetically Beautiful

Ever notice how laminated signs demand more attention than plain old run-of-the-mill paper signs? Adding a little bit of gloss to something makes it more authoritative. Making your comments look a little extra legit makes teammates more likely to notice, pay attention to, and obey them. That’s powerful. It’s worth it to invest a little time to add some polish to your comments.

This isn’t an entirely vain effort, either. Keeping your comments structured and predictable means reducing the cognitive load of reading styles. It saves brainpower for the fun stuff, rather than understanding what’s going on in the first place. If all comments look the same, they’ll be easier to scan, read, comprehend, and edit.

Consistency is key. You may want to work with your team to decide on an agreed-upon style. If you don’t have a style guide set in place for comments, here are some baseline rules to make your comments look great. These are taken straight from Nicolas Gallagher’s idiomatic-css repo, which provides much more comprehensive style rules if you’re interested.

• Place comments on a new line above their subject.

• Keep line-length to a sensible maximum, e.g., 80 columns.

• Make liberal use of comments to break CSS code into discrete sections.

• Use “sentence case” comments and consistent text indentation.

You can get way more fancy than these simple rules, but this is a solid foundation for making comments beautiful—in every sense of the word.

Beautiful Comments Are Only a Little More Difficult

Commenting CSS is important, and we should do more of it. We ought to be on the lookout for opportunities to add thoughtful comments, and we should take a little bit of time to make our comments look good and official. All these things take a little bit of elbow grease, but it’s a small amount of elbow grease.

I encourage you to get into the rhythm of putting more effort into your CSS comments. It’s a small investment, and it’s a noble one. Making a habit of writing beautiful comments means getting into the habit of communicating clearly with your teammates. If you can communicate clearly, you can collaborate effectively. And if you can collaborate effectively, you can build some seriously impressive things.