Your CSS could be more understandable

Rethink your code & make the world a better place

As a front-end developer at a large design agency, I regularly switch between projects. Usually we don’t have enough time to do handoff of every project detail. That’s one of the reasons why we keep our code as clean as possible at Mirabeau.

When I started learning about CSS around 15 years ago, I was very excited. Basic CSS is just describing how elements should be styled. Not some magic tricks. No hard to read syntax. No more tables, font elements or styling attributes.

However, websites get more complex every day. Some code bases live on a long time, being worked on by several developers. Code can get more difficult.

Over time I learned and thought of some principles for CSS. Let’s start with making CSS more understandable.

Naming stuff

One thing you shouldn’t do, and I’m sure you’ve heard it before: don’t name your class after what you’re trying to achieve. The same goes for defining variables.

The color above is not black

Instead, come up with logical and descriptive names. Like $color-primary or $color-inverted. Talk with designers about the classification of colors and other recurring stuff like margins.

Several times I’ve seen a variable being declared in SCSS with a name $color-black. Nothing wrong, right? Black’s just black, and if you need that color, just use it. Until you find the declaration $color-black: #8e8279. So here we’ve got black that’s rendered as brown.

Don’t use shorthands

Harry Roberts has written about it before: don’t use shorthands. They’re an anti-pattern, because they sometimes reset some properties.

I learned this the hard way a while back while working on some existing code. I needed to add a background color to an element, so I simply defined background: #95c300;. Then, a background image disappeared. It turned out a background image was shown on that element, in another CSS file.

Let’s take a short look at flexbox. Sometimes I see flex declarations written like flex: 1; or flex: 1 1 0;. This code doesn’t describe itself that well, but some browsers have trouble with executing it correctly as well.

Just use the longhand CSS properties. It describes your code better and reduces cognitive load for anyone new on your project.

Affecting other elements

One of the most basic things front-end developers don’t seem to get right is the following: lines. Items with lines between them are usually written in this manner:

li {
    border-bottom: solid;
li:last-child {
    border-bottom: 0;

Let’s describe our code. What we’re writing here is two things:

  • List item elements should have a solid border on the bottom
  • List item elements that are the last child shouldn’t have a border on the bottom at all

We can do this differently with the adjacent sibling selector.

li + li {
    border-top: solid;

The code above is described as follows:

  • List item elements that immediately follow a list item element should have a solid border on the top.

Writing code in such a manner makes it more logical to read. We’ve got three positive outcomes:

  1. Less lines of code
  2. No overwritten code or negation
  3. The code is more like how the design would be explained

I’ve also seen people use :not to write smaller CSS for this use case. However, making code smaller doesn’t mean it’s understandable.

Boy scout rule

While I was out camping with friends, they pointed out a rule they learned at scouting. When leaving your campground, tidy up everything better than how you found the place.

Later on I found the term boy scout rule used by developers. It’s a good principle for everyday life. We all know the feeling of disappointment when we find a place trashed. Don’t let it happen to others.

So let’s put it into practice. Refactor code instead of making things more difficult. Try to find some ‘extra’ time while working on an ongoing project. Use it to make existing code more comprehensible.

This is not all

There’s a lot to tell about writing understandable code in general. Several other things like setting up the right architecture of CSS aren’t covered in this article. I’ll leave that for another time. Now go and start writing better stylesheets!