CSS Rules of Thumb

Apropos of nothing, a few CSS tips that have nothing to do with browser incompatibilities, and everything to do with your own sanity when dealing with code you’ve written:

Comment your CSS files

This is incredibly basic advice that I don’t think is taken at all seriously enough. I’ve made an effort over the last few months to begin every CSS file I write with a comment block that looks something like:

 *  Title of the CSS file
 *  A Brief description of the CSS file's contents, and, if
 *  relevant, it's dependencies.  This should generally only
 *  be a sentence or three long, anything more, and the file's
 *  almost certainly attempting to do too much.
 *  <pre><code>
 *      <div class="the markup this css file expects">
 *          You'll be ever so happy you included this part
 *          in about three months, when you come back to this
 *          project, having completely forgotten it's
 *          structure and purpose.
 *      </div>
 *  </code></pre>
 *  @author     Mike West <mike@mikewest.org>
 *  @package    some_greppable_name

This is the basis upon which you can start writing reasonable CSS rules that you have a good chance of understanding the next time you read them. Especially the expected markup. You may think that’s overly verbose, and simply overkill for most projects, but without it, you’ll get lost when trying to map the file’s CSS to anything at all on the actual website you’re coding.

It’s important to put as much context into the CSS file as possible, because CSS is a complex language when you use it the way you’re supposed to. The more you rely on the cascade to reuse code and concepts, the more you’ll come to rely on good documentation to keep your bearings.

Write many, highly specialized CSS files

The general rule of thumb about documenting your code has a corollary: you should use lots of CSS files. You should be able to pick up a small, focused chunk of code, read through it, and understand more or less how it fits into the site as a whole. If it depends on some other chunk of code, that code should be referenced, but not included in the same file. Here’s why: long CSS files are opaque, confused, and unstructured. I don’t care how disciplined you are: this is true 100% of the time, without fail.

If you find yourself sifting through a CSS file, trying to figure out where best to stick a new bit of code, you’re simply doing it wrong. The fewer CSS files you have, the larger they’ll be, and the more tempted you’ll be to simply stick some new rules on the end to save time. You’ll do this because your teammates are doing it, and they’ll do it because you’re doing it. This is the path to poor code quality, poor code reuse, and simple insanity.

In short, I see long CSS files as the broken windows of web development. The longer and more convoluted the file, the more likely even the best developers are to simply make it more confused.

Name your files well

To whatever extent possible, you should develop a naming convention to make a file’s purpose clear, minimizing the chance that you’ll have to go looking for a good home for new code.

For example, on my current project, I’ve written a lot of modules that are all based upon the same root class. The markup might look like:

<div class="basebox">
    [Module basics go here]

<div class="basebox special">
    [Module basics, plus "special" markup go here]

basebox.css defines the presentation of the features common to all “Basebox” style modules. In that file’s documentation block, I’d define a @package of “projectname_basebox”. The “special” presentation is then defined in basebox_special.css, with a @package of “projectname_basebox_special”. The filename makes dependencies clear when determining import order, and the @package marker makes dependencies clear inside the file (and available to grep).

Style guides are good

You should organize a style guide for your team, and stick to it. As with any language, it’s helpful when your whole team speaks the same dialect. Insofar as that’s true, I think it’s more important that you agree on a set of rules defining how you write CSS, rather than my set of rules. The more your CSS looks like your neighbors, the more likely she is to understand your rules quickly when she needs to change them (and the more likely you are to understand rules you wrote months ago…).

That said, you should of course all write CSS like I do. Because it’s the right way. Here’s how and why:

Write code for human consumption

Your code should first and foremost be human-readable. Of course you want to deliver a single combined and minified CSS file to the browser, and of course that means that you’ll have to do some work to transform the nicely readable code you’ve written into something lean and mean for performance and efficiency (a good place to start would be Tim Huegdon’s article “Website Builds Using Make”).

So don’t worry about the performance penalties to writing long comments, detailing every tricky piece of your CSS. And don’t worry about the performance penalties of splitting your code into many easily understood chunks. There aren’t any. Your build process will combine all your files, and compress them into a single file that’s completely incomprehensible to human eyes. This is a purely mechanical act, and it’s something that should be scripted. Your concern when writing code should be your understanding of that code, not the browser’s.