How to make your SASS readable for the humans who actually read it

Photo by Pankaj Patel on Unsplash

If you’re a front-end developer like me, you probably find yourself writing a fair bit of CSS from time to time. Whether it’s your latest React SPA or the latest blog post on your personal website — chances are that you’ve written the CSS which makes both of those look fabulous.

What’s even more likely (because of the CSS-loving developer you are) is that you have come across other stylesheets either written by yourself years ago, long distant ex-employees or from that one guy on StackOverflow who’s GitHub Gist got more than a dozen stars.

One thing that I can be sure of is that all of these examples more than likely look like the opening to the gates of hell and make you want to run away before you’ve even read the first class…

I’ve been there more than once and I’ve definitely contributed to many spaghetti-code stylesheets in my time too.

Since starting at Butternut and being one of the many engineers who are responsible for the SASS/CSS that style butternutbox.com — I decided not to be that guy. To leave code in a better place than I found it and to #striveforbetter in every line that I write and contribute.

And If you’re reading this — there’s a good chance you want to be that guy too and you want to leave your CSS shining like a brand new pair of school shoes on the first day of term.

Well… there are a few things I’ve picked up and tried out along the way which might just help you achieve that shining stylesheet of nirvana.

Practise commenting

If there is one thing that I don’t see often enough is the use of good commenting in stylesheets.

And I’m not talking about:

// This works, dont' know why...

or…

// TODO: remove this class

or…

// fixes IE
font-size: 13.5px

But actual comments that you can leave other fellow developers to either:

1. Help them understand what a certain class, function or mixin does or should do
2. Describe the layout of the page/component that the CSS is being used for
3. To let them know they are looking at the correct stylesheet. I’m looking at you “nav.sass”

To provide an example, imagine we are writing the CSS for a Blog. In this example, we will be using Sass but these methods can be transposed into any kind of CSS syntax.

// A simple wrapper class that helps in wrapping the Blog page's
// content and ensures the content is centered 
.wrapper
  max-width: 500px
  margin: auto
  padding: 20px
	
  // This modifier class is used for when we want a post to be
  // wider than the default .wrapper class
  &--wide 
    max-width: 750px

In this example, the comments are able to provide a clear explanation as to what the first .wrapper class is designed for and also (if you follow BEM principles), an explanation of its modifiers too.

By just taking the extra minute to write a simple comment, it can go a really long way and can dramatically help the next developer who looks into this CSS sheet down the road (who may even be you).

Bonus tip: If you struggle to write a simple and clear comment for a class or element, there is a strong chance that either your class names are too vague or your styling has become way too specific and probably signifies that you might want to refactor.

Use comment ‘blocks’ to help separate your CSS

Now, this point may not be to everyone’s taste or preference but it’s something I have become a huge fan of doing as I write my Sass.

Sometimes stylesheets just need to be long files — for pages or components that are visually complex or they just have a lot of styling needed to look the way they are intended. In these cases, I use this style of comment blocks to help separate page sections:

Here’s an example:

////////////////////////////////////////////////////
// Blog Post - Hero
// This is the styling needed to render the Hero of
// every blog post. It's features a Title and
// a subtitle
////////////////////////////////////////////////////
.blog-hero
  ...
  &__title
    ...
  &__sub-title
    ...
////////////////////////////////////////////////////
// Blog Post - Content
// This class is used for the actual content of the
// Blog post itself and the content sits below the
// Hero component 
////////////////////////////////////////////////////
.blog-content
  ...

By separating our class names in this way makes it much easier to distinguish and also gives the reader a greater context of the use cases of these styles and where they should be used.

A couple of things to note when using these:

• At Butternut, we try to keep our JavaScript to about 80 characters in width and most of the time our Sass follows suit too. When using these blocks, make sure that the first and last lines of //////////... reach all the way to your character limit
• I try to keep two empty lines above and one empty line below my comment blocks. Like page headings, I’ve found that it’s easier to visually separate the styles this way
• Title your comment block. Like in the example above, the title not only explains the name of the overall page or component but also which element the following CSS corresponds to.
• Write your comments like you were writing a future explanation for yourself. Write like a human and a simpler longer comment is always better than a shorter more complex one.

Bonus Tip: For Sublime Text users, I have created a snippet that allows you to add these blocks in your Sass files easily

Follow BEM principles

Since I started writing Sass for a large organisation project like Butternut — perhaps one of the things that have helped me write better, more understandable and sustainable CSS is following BEM (Block Element Modifier) naming conventions.

I won’t go too much into what BEM is here but there are tons of great resources out there that do a great job of explaining what BEM is and how you can start following it in your project.

Here is a very simple demo of BEM in practice:

The ‘Element’ in BEM:

// Our base class name or 'Block' element
.blog-post
  max-width: 800px
  margin: auto
  width: 100%
	
  // Our 'element' which tells the reader that this
  // 'blog-post__title' should only be contained within a
  // 'blog-post' class 
  &__title
    font-size: 20px
    color: red

The HTML

<div class='blog-post'>
  <h1 class='blog-post__title'>My Blog Post Title</h1>
</div>

The ‘Modifier’ in BEM

// Our base class name or ‘Block’ element
.container
  max-width: 800px
  margin: auto
  width: 100%
	
  // Our 'modifier' class which when included in out HTML produces
  // a wider version of our .container component declared above
  &--wide
    max-width: 1000px

The HTML

<div class='container'>
  <h1>This is a normal container element</h1>
</div>
<div class='container container--wide'>
  <h1>This is a wider container element</h1>
</div>

Simply put, if you follow BEM’s rules and principles closely you’ll slowly start to realise the importance of a good class naming and structure and you’ll certainly start to become more conscious of how a good component is put together.

Following BEM not only make your CSS more understandable for a new viewer but it can also dramatically help when viewing at the HTML also (or however your components are rendered).

Use Sass/CSS linters

Before joining Butternut, I never used any type of linter at all (😱) and all of my CSS/JS and you-name-it languages were un-linted and all over the place.

Using code linters not only provide you with more reliable and functional code but they also encourage you to write scalable and also more consistent code too.

Using a linter for your CSS or Sass is also no exception and I believe everyone should be using one for any CSS they write.

I won’t go too much into detail of how you can get started with linters or how you can install them but there are a couple of options to look at when it comes to linting your CSS or Sass.

• sass-lint
• stylelint

Both of these examples should have easy ways to customise your linting experience and also show you how you can easily use them inside your favourite text editor too.

For a general rule-of-thumb — enable the default rules. See how you get on following them and then adjust them over time if they are too harsh.

Don’t be tempted to use ignores either as that just negates the purpose of adding a linter in the first place and your code still remains problematic and perhaps even more un-readable if there are // sass-lint-disable... comments everywhere.

Try and follow the linter rules and push yourself to follow them. You’ll probably become a better developer for it too.

Stop using !important

Now, this is potentially one of my biggest fears when picking up a new project. You check out the repo, browse through the folders, open up the CSS/Sass directory and start to peek around. Suddenly… there glaring at you, in bright-red linter errors… a sea of !important 's...

I’m sure I’m not the only one who has faced this fear a few times over my development career and I’m sure I won’t be the last either.

It has to stop.

Yes — I know that by adding just that single line saved your project from an unknown CSS side-affect and by doing so, also saved you countless minutes debugging and I’m also sure that you know you are going to go back and fix it up later but the matter of fact is… it never happens.

You never go back and revisit the addition of the !important nor do you go back to understand why that fixes your CSS.

I understand why the !important flag exists in CSS and for third-party/vendor stylesheets, it has its purposes. But the thing which aggravates me the most is that it is such a sledgehammer of a command when you only needed a screwdriver.

Remember kids…

If everything is important. Then nothing is important.

If there are dozens of !important's in your stylesheet - then technically, nothing is of importance and your CSS has just become a who-can-shout-the-loudest-contest based on which !important follows last for a particular element (don't forget the 'C' in CSS).

Instead — pause, take a second, take a quick break and come back and remove the !important you just added. I can promise you with some degree of certainty that it isn't needed and perhaps is an early sign that you need to clean up your website's styling and perhaps refactor the element you're working on.

As soon as you realise this and become proactive in not using !important, you'll become all the better a developer for it

Wrapping Up

Hopefully, the above ideas and guides should give you a better idea of how you can clean up your CSS in your projects and hey, maybe you even learnt something too!

Sure, all of these points are fairly opinionated so feel free to not abide by these rules 100% of the time. They are only tips and methods that I’ve picked up along the way and I think can help someone who was just like me at the start of their CSS journey.

For some further reading and ideas to improve or extend your CSS experience I’d recommend taking a look at the following:

• Autoprefixer — A must-have for reducing CSS bloat and ensuring the latest CSS is able to run in older browsers
• Using a reset stylesheet tool like Normalize to reduce your browser default styling
• Perhaps even using a CSS framework like Bootstrap, Foundation, Bulma or the 100’s of other frameworks out there which might just give you a hand when it comes to putting a site together. For 10 bonus points, think about how you can create your own CSS framework?
• React Transition Group for JS powered CSS transitions