June 13, 2013

CSS Dig: It’s Time to Refactor

On many sites CSS is like a neglected garage: you toss stuff in it for years always planning to get organized. Who knows what lurks in those corners? You might even be afraid to look. Multiple developers working with different designers, combined with a lack of standards, invariably lead to inconsistent and difficult to maintain code. Refactoring is your only hope.

But how do you start to identify the problem areas? Inspired by Nicolle Sullivan’s advice to “grep your styles”, CSS Dig is a Python script that runs locally to unearth properties and values from almost any website — from both linked CSS files as well as any code found in style blocks — to help you analyze, refactor, standardize and maintain your CSS.

A CSS Dig report of yahoo.com.

Figure 1 shows the three panels of a CSS Dig report. In the left panel all the properties that were found at the URL provided are listed. Those properties can be toggled, revealing and hiding data in the center panel. Details about the report appear in this center panel followed by counts and groupings of the declarations found. Each declaration can be clicked to reveal its origin in the combined CSS found in the third panel.

Here are a few examples. Note that you can run a report on any web page, not just the homepage.

Colors, Colors and More Colors

A good place to start your analysis is to identify the colors declared on your site. Having too many is often an indicator that the rest of your code could use refactoring. Do you really need 10 similar shades of blue or is this more likely the result of developers and designers grabbing the wrong color?

For example, in Figure 2 below, this CSS Dig report on huffingtonpost.com reveals the CSS files contain 264 different color values (though some evaluate to the same color, for example, #000 and #000000).

Huffington Post’s many colors.

Results like these indicate you probably need a style guide. Consolidate your blues and grays and reds into a simplified palette and make it easy for developers to pick the right one. If you’re using a CSS pre-processor (you are, right?) create variables and stick to them. After the refactor run the report again to see if anyone has strayed from the One True Path.

Apply this same process to consolidating font sizes, margins and paddings, and any other red flags that might be causing maintenance issues and ballooning CSS files. For example, note a few of the 22 unique z-index values found on msn.com.

...
z-index: 10;
z-index: 100;
z-index: 100000;
z-index: 100000000;
...

100 million! Can’t go any higher than that, right?

Coding Style & Standardization

Another area to look at is the consistency of your code. On many sites you’ll find color declarations like this:

color: #ccc;
color: #cccccc;
color: #CCC;
color: #CCCCCC;

All four are equivalent and will render the same but why not be consistent? CSS Dig will expose this problem. Make a decision as a team what style you want to use and stick to it. The same kind of standardization should be applied to many different properties.

Rules like these can seem like nit-picking — and they are — but if you’re working on a large code base they all serve a larger purpose: If your code looks as though one developer produced it you’ll simplify maintenance and help new contributors get up to speed.

Don’t Stop Now

After a close examination of your CSS you’ll likely realize that that fixing a few color variables and font sizes only scratches the surface. What you really need to do is refactor your HTML along with your CSS.

This is a harder problem, beyond the scope of this post and the CSS Dig tool, but to help get started Nicolle Sullivan recently release the slides of her presentation on refactoring Trulia. Here are a few of her suggestions along with a few of my own.

A few other resources:

Make Reports & Contribute

The CSS Dig GitHub repository contains the installation and usage instructions along with a more detailed technical explanation. CSS Dig was written primarily in Python with some light javascript for the UI. I’m by no means and expert in Python so please fork and help make it better or extend in new directions.

If you run into any issues please create an issue. Your feedback is appreciated!

Special thanks to @nedrockson for his help and advice.