Editor’s note: This article is part of our Code Optimization series, where we take a look at how to optimize coding for better efficiency in a bid to be better coders.
When designers talk about style guides, they usually mean an agreed upon manual on the coherent look and feel of a website or an application, with a well-designed colour scheme, typography, and UI that’s used across the whole project.
There’s another type of style guide we can use in web development as well, and it’s just as important but much more rarely discussed: style guides for the code itself. Code style guides are rather for developers than designers, and their main goal is to optimize CSS, or other code.
Putting proper code style guides into use provides us with a better organized, consistent code base, improved code readability, and more maintainable code. It’s not a coincidence that major tech companies, such as Google, AirBnB, or Dropbox make good use of them.
In this post we will take a look at how we can smartly optimize our CSS with the help of CSS code style guides.
Code Style Guides vs. Pattern Libraries
In our industry there is a certain degree of uncertainty about what we can call a style guide. A List Apart for example uses it synonymously with the term pattern library in this article, but we can bump into this kind of definition in other posts as well.
On the other hand, there are also publications, such as CSS Tricks or Brad Frost’s blog, that distinguish code style guides from pattern libraries. This latter approach probably takes us closer to a well-optimized website, as it allows us to handle code and design separately, so we will use this in this post.
Both code style guides and pattern libraries include a styling strategy, but a different kind. Pattern libraries, such as Bootstrap, Zurb Foundation, BBC’s Global Experience Language, or MailChimp’s pattern library, provide us with a UI with premade CSS classes, typography, colour scheme, sometimes a grid system and other design patterns.
CSS code style guides, such as Evernote’s or ThinkUp’s (or the ones mentioned in the intro) contain rules about how to write CSS including things like naming conventions, file structure, property order, code formatting, and others.
Note that living style guide generators, such as KSS, Styledown, or Pattern Lab, generate pattern libraries and not coding style guides. While pattern libraries are also highly useful and elevate the web development process, they don’t allow us to optimize code itself.
Build Your CSS Code Style Guide
The final goal of a CSS code style guide is to ensure we can work with a consistent, easily debuggable code base written by developers who all follow the same code styling rules. Creating a CSS code style guide may take a little time but it’s worth the effort, as we only have to do it once. Then we can use the same style guide across different projects.
It’s important to note that the best style guides don’t only contain the styling rules themselves, but also examples of good and bad usage, as this way developers can more intuitively understand the rules.
For example AirBnB shows good and bad examples to developers in the following easily digestable way:
File Structure
First, we need to figure out a logic according to which we will organize our CSS files. For smaller projects one CSS file may be enough, but for larger ones it’s always better to break up the code, and concatenate the separate files later in production.
Some style guides such as ThinkUp’s, also warns us about not using inline or embedded styles unless it’s unavoidable; it’s also a useful rule that’s worth applying.
Nesting
Nesting is a great feature in CSS, but at times it can go out of control. No one feels particularly happy, especially in the middle of a frustrating debugging process, bumping into extra long selectors like this:
.class_1 .class_2 #id_1 #id_2 li a span { color: #bad; }
So it’s always good to set up a reasonable nesting limit, for example GitHub chose three levels in its style guide. By limiting nesting we can also force ourselves to write a better structured code.
Naming Rules
Using coherent naming rules for CSS selectors is crucial if we want to understand our code months or even years later. There are many solutions out there, and there’s only one strict rule we need to follow i.e. a selector name cannot start with a number.
The four common styles used in selector naming are .lowercase, .under_scores, .dash-es, and .lowerCamelCase. It’s okay to choose any of them but we need to follow the same logic across the whole project.
Using only semantic selector names is also essential if we want to have meaningful code. For example, instead of .red-button (which doesn’t show what the button does) it’s better to use the .alert-button name (which says what it does), as this way, we enable developers (and our future selves) to understand what said button does.
Moreover if we want to change its colour from red to something else in the future, we can easily do it without a hassle. There are also premade CSS naming conventions, such as the BEM (Block, Element, Modifier) convention, that result in a consistent naming structure with unique and meaningful names.
Formatting Rules
Code formatting includes things like usage of whitespace, tabs, indentation, spacing, line breaks, etc. There’s not really a universally good or bad method in formatting, the only rule of thumb is to choose coherent rules that result in a readable code, and follow them through.
Dropbox for example requires developers to put spaces after the colon in property declarations, while Evernote uses two spaces for indentation. We can set up as many formatting rules as we are comfortable with, but never more than it’s possible to grasp.
Declaration Order
Ordered things are always easier to see through, and ordering CSS declarations (properties with their values) according to a rule that makes sense results in a better organized code.
Take a look at for example WordPress’s property ordering rules, it defines the following simple but logical baseline for ordering in which properties are grouped by their meaning:
- Display
- Positioning
- Box model
- Colors and Typography
- Other
Units and Values
Deciding upon how we want to use units and values is not only important to achieve a consistent code look, but also if we don’t do so, we may end up with something weird
Just imagine a site that alternately uses px, em, and rem length measurements. It won’t only look bad in the code editor, but most likely some elements will be surprisingly small or large on that site.
We also need to make decisions about colour values (hexadecimal, rgb, or hsl), and whether we want to use shorthand properties and according to which rules. There’s an instruction that’s included in every CSS code style guide I bumped into, i.e. don’t specify units for 0 values (really, just don’t).
.class { // good margin: 0; // bad margin: 0px; // bad margin: 0em; // bad margin: 0rem; }
Commenting
Commenting code is essential in all languages, but in CSS it doesn’t only facilitate debugging and documentation making, but also sections CSS rules into logical groups. We can use either the /* ... */ or the // ... notation style for comments in CSS, the important thing is to stay consistent with comments throughout our project.
Idiomatic CSS for example establishes a meaningful commenting system that even uses some basic ASCII art, and results in beautifully organized code:
