At the heart of writing good CSS code is maintainability. As a developer, one of the best practices you should always strive for is writing understandable and maintainable code. To achieve maintainability, a developer must put into consideration the next reader/developer that will make use of the codebase.

A CSS codebase is said to be maintainable when you can make changes to it without causing unintended side-effects elsewhere.

In this post, I will share everything you need to know about writing maintainable css, Here's what I will cover:

  1. Introduction to Modules and what they are
  2. Semantic class naming
  3. Code structuring
  4. Commenting

Introduction to Modules

For a code to be maintainable, it has to be created and structured in the form of modules but what are modules?

A module is a distinct independent unit that can be combined with other modules to create a more complex structure. It is a reusable chunk of HTML and CSS that performs a specific function. On a webpage, a sidebar, navbar, a footer can be classified as modules.

Creating your HTML and CSS in this form makes it more "digestible" for a reader or other developers. Although writing your HTML/CSS in chunks is great, naming your classes semantically makes it even better.

Semantic naming

Semantic class naming is a style in which we use class names that describe what an element is, or it’s intended purpose, rather than how it looks.

 <div class="card">
       <span class="card__img"></span>
       <div class="card__content">
           <ul class="card__list">
               <li class="card__item">Sketch</li>
               <li class="card__item">Figma</li>
               <li class="card__item">Invision</li>
           </ul>
       </div>
  </div>

As seen above, the classes are easy to read without needing to be interpreted. It also becomes very glaring where the module begins and ends.

Naming is the most vital part of writing maintainable CSS. It is important that when naming classes we avoid names that describe how an element might be presented rather than what they mean. For example

   <div class="color-red"></div>

Semantic CSS helps to convey what an element represents just by looking at it. This would ensure that the next developer that would come across the codebase can easily understand what a section or module is all about, just by mere staring at the name. It's also important to use naming conventions like BEM or SMACSS.

BEM (Block, Element, Modifier) is a naming convention for classes in HTML and CSS. Its goal is to help developers understand the relationship between the HTML and CSS in a given project.

   <header class=”header”>
       <img class=”header__logo”>
       <div class="header__img"></div>
    </header>

These classes are easy to read without needing to be interpreted. It's clear where the module begins and ends. This is what BEM helps with.

Why use semantic HTML

  • It's easier to find on your code editor
  • They are easier to debug -you can easily debug a class that is semantically named
  • They produce a small HTML.


Structuring

Another thing to address when it comes to maintainability of code is how you structure it. This is one aspect I have fallen prey to. Sometimes it becomes tempting to bring in a class defined in module A to module B. The ideas of entangling classes from different modules could pop up because you are trying to follow the DRY rule, "Don't repeat yourself".

For example I decided to bring in a class called “card__item” from a module I have previously created because the class contains the style I needed. This can alter the way the code is understood and it becomes extremely difficult to maintain. 

  
   <header class=”header”>
       <img class=”header__logo”>
       <div class="header__img"></div>
   	 <div class="card__item">Sketch</div>
    </header>

If we try to combine them we will entangle two modules with CSS overrides. This entangling by definition is complex which in turn is hard to maintain.

Commenting

Commenting involves placing human readable descriptions inside of computer programs detailing what the Code is doing. Proper use of commenting can make code maintenance much easier.  

A user should be able to utilise a previously written CSS without ever having to look at the code, simply by reading the comments.