Writing maintainable CSS
Tags: beginners, css
Published: 2019-12-10 18:22:48

---
title: Writing maintainable CSS
published: true
description: A beginners guide on writing maintainable CSS
tags: beginners, css
series: FrontEnd Development Zero to Hero
---
Maintainable code is one of the joy of software development. The feeling you get when you open a codebase and the smile on your face and in your heart is almost _priceless_. Albeit some might argue that this just applies to programming codebases like _JavaScript_ or _PHP_ but, i guess that'll mean that _maintainable CSS_ is the joy of a frontend developer who has a specific soft spot for CSS.

It is quiet easy to get started with CSS as i have mentioned in the [introduction to CSS](https://dev.to/ziizium/introduction-to-css-1fm) but, as you proceed you'll come across terms like [specificity](https://dev.to/ziizium/css-specificity-ilk) and [the cascade](https://dev.to/ziizium/the-css-cascade-47kb).

The more your codebase grows you'll have to keep track of so many things like [variable](https://dev.to/ziizium/css-variables-1n72) and [selector](https://dev.to/ziizium/css-selectors-1ch3) names. A _naming convention_ can take care of the latter and _good naming_ can take care of the former but you can do more to help yourself or any other developer working on this codebase in the present or in the future.

In the word of [Edsger W. Dijkstra](https://en.wikipedia.org/wiki/Edsger_W._Dijkstra) in his book [_A discipline of programming_](https://www.amazon.com/Discipline-Programming-Edsger-W-Dijkstra/dp/013215871X):

> __... I was forced to admit that most programs are presented in a way fit for mechanical execution but, even if of any beauty at all, totally unfit for human appreciation.__

There are many techniques that you can consider to make sure your CSS codebase is fit for human appreciation. We'll discuss them and its up to you choose.

_Contrary to the tradition of this series this post is <b>more of theory than code</b>._

<hr>

Maintainable CSS is about writing CSS that is modular, scalable and maintainable.

When we talk about modular code we mean __modules__ which are independent parts of the web page that can be combined with other parts to create the entire structure of the web page. Examples include _header_ and _navigation_.

__Scalability__ on the other hand means when the codebase increase in size it is easy to maintain.

__Maintainability__ means changes can be made without causing a chain of reactions that will lead to another problem elsewhere in the codebase.

_From a beginners perspective_ the following is an _incomplete list_ of recommendations on writing maintainable CSS: 

* Write comments
* Use semantic HTML
* Use semantic class names
* Use ID's sparingly
* Use a naming convention
* Make your code readable

###__Write comments__

Comments _serve as a note_ to yourself or another developer that will work on your codebase at some point in time. They should be well written and descriptive of _what is going on_ or _why you made a coding decision_.

You might be solving a particular problem and the solution just popped into your head out of nowhere and then you go ahead and implement the solution and voila! it works!.

At that moment in time you should explain the critical part of your implementation in a comment. When you open your codebase after a long period of time you should not be surprised that the comments might be your guide.

Take the following hypothetical example:

```css
.header {
  /*
   * The margin bottom is applied to create an outer spacing
   * thereby preventing the header from touching the main
   * content.
  */
  margin-bottom: 2em;
}

.box {

  /*
   * The padding property is actually shorthand for four
   * other properties namely padding-top, padding-right
   * padding-bottom, padding-left.
  */
  padding: 3em;
}
```

The following tweet might not be about CSS but, it says a lot about the importance of comments in a codebase.


{% twitter 1107764182437355520 %}

###__Use semantic HTML__

Semantic HTML is good HTML with tons of accessibility features for free. When you write semantic HTML with meaningful class names (discussed next) you are forcing yourself to write good CSS. 

Look at the following example:

```html
<header>
  <h1>Header here</h1>
</header>

<main>
  <section>
    <!--Text here -->
  </section>
</main>

<footer>
  <!-- Footer text here -->
</footer>
```

Compared to

```html
<div>
  <h1>Header here</h1>
</div>

<div>
  <div>
   <!-- Text here -->
  </div>
</div>

<div>
  <!-- footer text here -->
</div>
```

###__Use semantic class names__

Semantic class names describe the purpose of an HTML element and __not what it looks like__ nor __the styles applied to it__.

```html
<!-- this -->

<header class="hero">
  <h1><!--Text here--></h1>
</header>

<main class="site-content">
  <p class="introductory-text"></p>
</main>

<!-- compared to this -->

<div class="f1 pd2 mt3">
  <p class="p1"></p>
</div>
```

Some of the advantages of semantic class names include:

* They are easier to find
* Easier to debug
* They are readable

###__Use ID sparingly__

ID selectors have a _higher specificity than classes and attribute selectors_. When you use lots of ID's in your CSS they will be difficult to override and you'll have to resolve to `!important` to make sure certain styles are applied.

The recommendation is to _use an ID when there is only one instance of a thing_ and use _class selectors_ when there are several.

Given the code snippet below:

```html
<header id="header">
  <p id="paragraph-1">Lorem ipsum dolor sit amet, consectetur adipisicing elit</p>
  <p id="paragraph-2">Lorem ipsum dolor sit amet, consectetur adipisicing elit</p>
</header>
```

You can write this instead:

```html
<!-- There are more than one paragraph so its best to use a class -->

<header id="header">
  <p class="paragraph">Lorem ipsum dolor sit amet, consectetur adipisicing elit</p>
  <p class="paragraph">Lorem ipsum dolor sit amet, consectetur adipisicing elit</p>
</header>
```

And your CSS would be:

```css
.paragraph {
  /* Your styles here */
}
```

Mind you if you use `!important` on two selectors, the one with the _higher specificity_ wins.

```css
/* specificity 0001 */
article {
  background-color: yellow !important;  /* This will be ignored */
}

/* specificity 0002 */
body article {
  background-color: green !important; /* The browser will use this */
}
```

###__Use a naming convention__

Naming conventions provide you with recommended guidelines that you can employ to make your CSS more readable and maintainable.

We've discussed this before, you can read the post below.

{% link https://dev.to/ziizium/css-naming-conventions-5gd6 %}

###__Make your code readable__

Readability is one of the tenets of maintainable code. The ability to look at a codebase and gain confidence that you can make sense of it speaks volumes.

```css
/* This */
.header,.logo{padding:1.2em;margin:2em;width:500px;}

/*compared to this*/
.header,
.logo {
  padding: 1.2em;
  margin: 2em;
  width: 500px;
}
```

These are just recommendations, when you write more CSS you'll discover your own way of writing maintainable CSS, when you do, just make sure that any developer that will inherit your codebase won't find it difficult in making sense of it.

If you would like to dive deeper on this subject take a look at the following resources:

* [MaintainableCSS](https://maintainablecss.com/)
* [Write better CSS](https://blog.theodo.com/2018/06/write-better-css-part-1/)

<hr>

We've come to the end of our discussion on CSS for [this series](https://dev.to/ziizium/frontend-development-zero-to-hero-j0j). Up next, _References and Resources_ to further your CSS learning.