Is it good to enforce a CSS code style guide?

The goal

Have SCSS stylesheets that look as if there written by 1 developer while working in a team.

Is this even an issue to begin with?

Frontend developers tend to be strict on the way they write CSS/JS but that’s not the main reason. Having organized and clean code is key for fast iterations. Everyone wants to be Agile these days.

If all the files look the same it’s easy to read and easy to pick up again in the future should the project require more phases.

How did we do it?

All recent projects at TBSCG have a build process (Grunt) to compile SCSS, JS, HTML, etc. So we simply included a linter task in that process.

We created a rules file to specify what want we wanted to enforce. Things like:

  • HEX color codes should be in variables. And even better, all in 1 file.
  • Spaces between brackets and class names.
  • Break lines between rules.
  • No !important anywhere 😎
  • Leading zero ( .5 vs 0.5 )
  • Order of the properties (did you know ordering the properties generates smaller gziped files than unordered?)

We only add this linter task to the dev build, so it will never crash in production should we commit a file with errors.
However, with the dev task Grunt will stop as we configured this to be errors not warnings.

Alright, I know what you must be thinking. In some cases hacks might be necessary (we all know how pesky CSS can be), there is a special markup to bypass the enforced rules. It should be used in very special cases. Otherwise the linter makes no sense.

Examples

Because code speaks better than me. Here are some examples of what I mean.

The following code fails to comply with the linter rules. Thankfully Atom knows that and highlights the problems even before I run my Grunt task, so I can fix them as I go.

linter-scss-errors

When running the Grunt task (in case your IDE does not warn you). Here’s the output:

SpaceBeforeBrace: Opening curly brace `{` should be preceded by one space

PropertySortOrder: Properties should be ordered bottom, display, position, width, z-index

DuplicateProperty: Property `bottom` already defined on line 4

SpaceBeforeBrace: Opening curly brace `{` should be preceded by one space

DeclarationOrder: Expected item on line 14 to appear before line 12. Rule sets should be ordered as follows: `@extends`, `@includes` without `@content`, properties, `@includes` with `@content`, nested rule sets

Now here’s the code fixed to pass the linter. Looks better, doesn’t it?

linter-valid-scss

Using it in a real project

Everything is great and all but can this be used in a real project? Does it make sense? Is it productive?

I won’t deny there’s a learning curve for those developers who are used to write code without any strict code style. I truly believe this is good in the long run. Once you get used to the rules, you’ll use them as you type.
The IDE is also important, you need to install the proper plugins to detect the linter config file, so it warns you without the need to run Grunt. In our case Grunt is our second line of defense. Your own editor should be the first to let you know.

Here’s the opinion of Artur Spulnik a Web Developer at TBSCG who worked with me on this real experiment:

Thanks to these principles code was much easier to read and maintain. I had to summon all my knowledge about the alphabet to correctly queue all definitions. There was a lot of pain in the beginning with operators order, and those wild spaces (or lack of them). But with practice comes success and I felt boost of productivity. Especially in terms of teamwork.

Have you ever written code this way? If you haven’t, will you give it a try?

Share

Published by

Ricard Torres

Ricard is a Senior UI/UX Developer @ TBSCG. Based in Barcelona he also plays guitar, takes photographs and teaches Haidong Gumdo.

3 thoughts on “Is it good to enforce a CSS code style guide?”

  1. Totally agree – the same guidelines should be made in any place where teamwork is a part of it (i.e. Java). The work is much more easier when you need to change sth and you know what to expect in file and where to find a place. Especially in the CSS wilderness…
    Another topics to add could be the naming convention of classes, file structure and convention of keeping media together (or separate? :)). Nice to read (didn’t know that order matters in term of filesize)!

    1. The naming convention is another hard battle. I’ve read about BEM an others http://getbem.com/introduction/ and I don’t 100% like any of them.

      I do believe we should be consistent however. Maybe, if the project is using Bootstrap we should try to follow Bootstrap’s convention. At least that’s what I try to do.

      About the file size, I can’t find the exact post where I read it but here’s a similar one with some tests with different sorting: http://peteschuster.com/2014/12/reduce-file-size-css-sorting/

      Thank you for your comment Marcin!

  2. In general the BEM idea is sth what I do not like. Messing with double underscore and double dashes… thats sth really nasty. Especially when you need to comment part of markup in XSLT and it scream about wrong double dash inside comment…

    The idea behind BEM is nice (see the structure of CSS classes on the first look) but why it is so messed in real life? Recently I saw delivered front work – instead of keeping the “diff” between two variants guys extend container with container–padding class…

    It is hard to pick the proper way but long class names with double__underscore–or–double–dash is not the way to go imho…

Comments are closed.