Writing maintainable CSS

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 but, as you proceed you'll come across terms like specificity and the cascade.

The more your codebase grows you'll have to keep track of so many things like variable and selector 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 in his book A discipline of programming:

... 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 more of theory than code.

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:

.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.

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:

<header>
  <h1>Header here</h1>
</header>

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

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

Compared to

<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.

<!-- 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:

<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:

<!-- 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:

.paragraph {
  /* Your styles here */
}

Mind you if you use !important on two selectors, the one with the higher specificity wins.

/* 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.

CSS Naming conventions

Habdul Hazeez ・ Dec 9 '19

#beginners #css

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.

/* 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
• Write better CSS

We've come to the end of our discussion on CSS for this series. Up next, References and Resources to further your CSS learning.