CSS Guide


Improving Code Readability

To ensure that other people can come in and easily find where to make changes, we need to have adequate documentation (not extensive, some coding knowledge required) that plans for and show what we are using on the website as well as where it’s being used, and simple, organized, clean and clear to understand code.

Here are a few hard and fast rules to making sure we can accomplish this:


This is more like a general advice, it’s not specific to CSS. When you’re about to develop something, start by thinking about it. Ask yourself a few questions:

  1. How would I do this?
  2. Is there another way?
  3. How can I optimize it (to be maintainable, clean, cool, etc.)?

Rushing into the code may lead to time loss. What if you spent one hour creating something to realize you can’t do it this way and have to start all over again? This shouldn’t happen.
Spending hours on a CSS slideshow to end up with SlidesJS or Adaptor is a shame. Not because you didn’t succeed, but because it was a complete waste of time. On a tight deadline, you may suffer from such a mistake.


CSS is a simple language but things can easily become complex. Especially if you want them to be. In most cases, the simplest idea is the better idea. When you want to achieve something, always ask yourself if there is not a simpler way to do it. You’d be surprise how often the answer is ‘yes’.
As an example, if you want a really simple horizontal navigation with only links, you have multiple ways to do this:

  1. Float the list elements
  2. Set the list elements to inline
  3. Set the list elements to inline-block

Pick the simplest and set the list elements to inline. No need of a clearfix hack. No need of an inline-space fix. It only needs a regular padding, nothing more. Etc…


DRY stands for Don’t Repeat Yourself, and once again it’s not specific to CSS. It’s more like a common practice when you’re coding, whatever the language you’re dealing with.

So the main idea is to avoid repeating the same chunks of code X times when you can do it only once. In some languages, it can mean using functions but in CSS, it often means using reusable classes instead of targeting a specific element (more on that in the next section about OOCSS). However, sometimes it’s something really simple like refactoring. Let me explain myself.

If you happen to spot a snippet of code multiple times in your style sheet, it could be a good idea to refactor it in order to end up with only one occurrence. Have a look at the following:

.navigation li {
  color: #333;

.navigation li a {
  color: #333;

/* Refactoring */

.navigation li,
.navigation li a {
  color: #333;

See? You may wonder what the point of this is since the result is clearly the same. There are two things to consider: performance and maintainability.

About performance: less lines means faster parsing for the browser’s CSS parser. To put it simple, the parser will apply the color to both rules at once instead of doing it twice.

About maintainability, I think it speaks for itself. By doing this, you only have to change one line instead of two if you have to edit the color. Okay, no big deal when it’s only 2 lines to edit. But what about 50? Or 300?

Further Reading on DRY CSS

  1. DRY CSS, don’t repeat your CSS by Steven Bradley
  2. DRY CSS: a don’t-repeat-yourself methodology for creating efficient, unified and scalable style sheets by Jeremy Clarke


What is this thing?

OOCSS stands for object-oriented CSS. You’ve probably all heard about object-oriented programming languages. Basically, it means using “objects”, usually instances of classes (which consist of attributes and methods). So you may ask, what the relation with CSS could be?

First of all, let’s say it’s more like a concept or best practices than a real thing. CSS can’t really be object-oriented since it’s not a programming language: there are no namespaces, no functions, no methods, no programming classes, no conditional statements, etc. This is why some people will laugh when you talk about OOCSS.

Even if I have to agree with this, we can still optimize the way we do CSS to ease the process, make websites faster and improve maintainability.

How do we do that?

To put it very simple, it means using classes. A lot of classes. Think of your website with “modules” or “components” if you want. Try to spot repeated patterns and make them “objects” (classes) in order to reuse them.

To be a little more precise, it would mean essentially two things:

  1. Separate structure and appearance
  2. Separate containers and content

Separate structure and appearance

Separate structure and appearance can be important since graphical stuff can be used in multiple places on the website and in various types of elements, right? Take the following chunk of code, it can fit to a button, to a box, to a picture, whatever:

.my-box img {
  border: 1px solid #444;
  border-radius: 5px;
  box-shadow: 0 0 5px rgba(0,0,0,0.1);

Now instead of what we’ve just done, we could create a class named skin or something, and apply it to the elements that need it.

.skin {
  border: 1px solid #444;
  border-radius: 5px;
  box-shadow: 0 0 5px rgba(0,0,0,0.1);

This results in a much more comprehensible and maintainable style sheet and faster parsing.

Separate container and content

I think this is one of the most important rules of OOCSS: code independent components, not stuff for a specific place in your current design. Things should be reusable whatever their place on your site is without coding them again. Let’s take the following example:

#main h2 {
  color: #343434;
  font-size: 25px;
  line-height: 20px;
  border-bottom: 1px solid rgba(0,0,0,0.2);
  box-shadow: 0 1px rgba(255,255,255,0.4);

Okay. Now what if I want the exact same styles on a level-2 heading in the footer? Or, to style a level-3 heading in the exact same way (for whatever reason)? The right way to go would be to create a class and give those styles to this class, not to the elements itself.

What about the “never use IDs” thing?

When Nicole Sullivan came up with the concept of object-oriented CSS, this one was one of the hottest topics. Indeed CSSLint, a CSS code quality tool by Nicholas C. Zakas and Nicole Sullivan, recommends against the use of ID selectors.

To understand Nicole’s point of view, it’s important to understand that IDs can involve some specificity issues since they have the highest specificity score. Take the following code as an example (from CSSWizardry – see the live JSFiddle here):

To turn the first Twitter link black, you have two options: either give it an ID, or using the hammer bash !important. If header was a class instead of an ID, the problem wouldn’t have existed.

This is the part why Nicole Sullivan said “no ID”.

I’ll end this section by quoting Harry Roberts on the topic:

[…] I have decided that a blanket ban is sensible. Save yourself many potential headaches and never use IDs in your CSS files.

But of course, IDs can in principle still be used and are perfectly valid. 🙂

What’s my feeling about OOCSS?

As far as I’m concerned, I’m not entirely familiar with it. Mostly because I’ve never worked on a huge website involving multiple front-end developers. Let’s face it, this is probably very useful for larger architectures, but not for the little one-page website you do for your baker.

However, even if I don’t use OOCSS in my projects, I try to focus on important things like reusability of components, maintainability of the style sheet, performance and such. Those are the things OOCSS focuses on, so in some way, I’m not so far from it.

Further resources on OOCSS and the ID question

  1. An introduction to OOCSS by Louis Lazaris
  2. Object Oriented CSS by Nicole Sullivan
  3. OOCSS.org
  4. Don’t use IDs in CSS selectors? by Oli Studholme


The final suggestion to improve readability is a simple one: use comments to explain what you are doing to others that would see it after you.

The reason behind it is simple. Most people people have absolutely no idea what’s going on in your head. If something were to happen to make you unavailable to the rest of the team, we would be given the task of “figuring it out” by reading your uncommented code and fiddling with the browser developer console to see what works and what doesn’t to get the outcome that we need. This can take 5 minutes. It could even take an hour of unplanned work.

Scenarios like this can be prevented with some simple comment flags, explaining things like context, reasoning, and in some cases, how the code actually works.

Here are a few general rules for comments

Add Flags

One of the best ways to explain context is the use of Comment Flags. Like this:


This type of flag helps a person to scan a large document and quickly find the code that has been sectioned into a specific context. In this case, the context is the styles for the Documentation part of the website. See how helpful this would be?

To show further context

0 replies

Leave a Reply

Want to join the discussion?
Feel free to contribute!

Leave a Reply

Your email address will not be published. Required fields are marked *