Fig. 3 A Guide for Developers

CSS as Read by Humans

Practical techniques to make your CSS more readable and play better with others.

Written by Andy Rossi November 05, 2015

There’s a 100% chance that another developer will be reading your CSS code. It happens. It’s not worth developing overly-complicated systems that may help in the short term, but leave new eyes wasting time trying to find where things are or how they connect.

A project could be taken over by another team down the road. Make the transition as easy as possible for them. “Where are the styles for the mobile header?” “Why is this z-index so specific?” Don’t put them in a place where onboarding takes longer than it should.

Why not be nice and write CSS under the assumption that somebody else will be knee-deep in it? Here are a few easy checklist items that can (and will) improve readability, “shareability”, as well as include a bonus side effect of making your CSS more organized. Win-win!

Better partial structure

There is such a thing as over-engineering a project structure. Breaking styles into too many individual files makes searching for lines of code that much more difficult, especially if the person doing the searching isn’t you.

For example, a project could contain Sass partials with similar names. global-navigation and global-footer-navigation would be better served wrapped into a single file called navigation. Split that file up using comments. Keep the files topical. If there are more than two navigation-related partials in a project, the structure might need to be revisited.

Also, the names of the files contained in the project should be descriptive. general doesn’t do it for me, but grid does. I know what’s in the grid partial–it’s styles for the grid.

You’re welcome.

Alphabetical rules

This is an easy one. Writing CSS rules in alphabetical order results in lists that are easy to scan and helps prevent the possibility of duplicate rules. It takes some getting used to and I’m sure you’ll be singing the ABC song in your head for a bit.

(Better) Comments

Did you know that you can add comments to CSS documents?! It’s true! Comments can be used to identify and break up large blocks of code. Also, comments can be used to explain the reasoning for seemingly strange and random developer decisions. The more attention-grabbing the comment, the easier it is to spot a specific section while scrolling through a document. Comments are a navigation system and can only help with readability and organization.

Use comments to break up topical chunks of CSS code

Explain why a decision was made if it wouldn’t be obvious to the developer


Each CSS rule requires a colon and a semicolon, even if it’s the only rule for a selector. Treat the semicolon as a rule terminator.

Stylus, a CSS preprocessor, allows for rules without either colons or semicolons (as well as eschewing brackets). If you use Stylus, please do not subscribe to that style. This makes the code more difficult to read and it saves absolutely zero time. As a bonus, Stylus-syntax files get more difficult to read the longer the document becomes. Fortunately, Stylus compiles with colons, semicolons, and brackets anyway.

Cater to humans instead of gimmicky syntax.

Source Maps

When compiling Sass, make sure to include a source map. After all styles have been minified, it’s very difficult to debug style issues and find the actual offending line. Browser developer tools cannot help you unless you give it something to work with. Source maps allow the browser to connect compiled Sass to its original pre-compiled source structure. Yes, this is super helpful.

main.css:259 can now become _global-header.scss:15 when inspecting through a browser’s dev tools. Isn’t that much easier to read? main.css is a lie; it’s compiled. _global-header.scss is the file that needs to be edited.

To enable source maps on compilation, add the —sourcemap flag to the sass command (if you are running sass in a terminal). A lot of Sass compilation tools and build systems1 have this option turned on by default because it’s the nice thing to do. You might not have to do anything except make sure your browser of choice has “Enable CSS source maps” turned on.

Make sure to tell the person working on your CSS to enable this behavior in their browser. It’s up to you, the original developer, to assist others working on your code.

And there we go…

It takes a bit more effort to write readable code, but it’s totally worth it. Keep developer onboarding time to a minimum, direct them to sections of CSS as quickly as possible, and don’t make them feel stupid if only a single line of CSS needs to be changed and it can’t be found.

Let the browser deal with reading compiled CSS. That’s its job. The source needs to be as organized and as readable as possible for actual humans to consume.

Finally, do not develop for yourself. Develop under the assumption that the authored code will be handed off, because there’s a good chance that it will be.

  1. For example, grunt-contrib-sass has source maps enabled by default