Maintainability Guide

Published on Jun 17, 2009 (updated Feb 5, 2024), filed under development (feed). (Share this on Mastodon or Bluesky?)

This and many other posts are also available as a pretty, well-behaved ebook: On Web Development.

This documentation on maintenance and maintainability is a beginning [which was continued with a more comprehensive guide in 2018]. I’ve been focusing a lot on these topics over the last few weeks; they are topics that deserve far more attention.

Introduction
1. Definition
2. Assumptions
Characteristics of Maintainability
Techniques and Recommendations
Update (January 24, 2018)

Introduction

Maintainability is important in order to deal with change. Good maintainability means making change easier and more affordable, and avoiding change that is not necessary. This document discusses maintainability with special focus on web development.

Definition

Maintainability is most commonly referred to as “the ease in which a system [for instance, a website or web application] can be modified or extended,” quoting Jeremy D. Miller.

Other definitions suggest: “Maintainability is defined as the probability of performing a successful repair action within a given time. In other words, maintainability measures the ease and speed with which a system can be restored to operational status after a failure occurs.”

Wikipedia relates maintainability to the ease of a software product to be modified to “correct defects, meet new requirements, make future maintenance easier, or cope with a changed environment.”

Assumptions

Both traditional software development as well as web development are about probability. Improving maintainability includes minimizing the probability of code changes.
Change has a cost, and that cost is the motivation to improve maintainability.
Change is inevitable, yet there is change that is avoidable.
In web development, HTML changes are most expensive (as in almost all cases, there are more HTML documents or templates than style sheets or scripts).

Characteristics of Maintainability

Understandability

A maintainable system is understandable. This means, code is structured, follows conventions (for instance, coding and formatting guidelines), and is either “self-explanatory” or commented so that everyone involved in the development can understand what the code does.

Separation of Concerns and Orthogonality

To achieve easier maintenance concerns have to be separated, which means breaking the system into distinct features that overlap in functionality as little as possible.

Programming languages allow to separate concerns by the means of objects; design patterns like MVC (Model View Controller) allow to separate concerns by splitting them into data processing, presentation, and content; standards like HTML, CSS, and JavaScript allow the same by separating structure, presentation, and behavior.

Separation of concerns allows to change one thing at a time. The goal to achieve this is orthogonality: “The basic idea of orthogonality is that things that are not related conceptually should not be related in [a] system.”

Extensibility

A maintainable system is also extensible. This means it is easy to add new functionality and features. On a high level this can be achieved by focusing on simple solutions; this document yet owes more options when it comes to extensibility.

Techniques and Recommendations

Keep Things Simple: Use Only What Is Absolutely Necessary

Being rigid about how much and what code gets actually used is not just good for efficiency and performance, it is also a healthy mindset to apply when it comes to maintainability.

For instance, you can make use of HTML context to style elements: Assigning every child element that has a unique parent element a certain class usually indicates that things could get simplified. See the following markup example:

<ul id="results">
  <li class="result">
  <li class="result">
  <li class="result">
</ul>

To style the li elements all in the same way, you don’t need a result class. You can use the context instead (#results li):

<ul id="results">
  <li>
  <li>
  <li>
</ul>

Both software and web development usually mean several ways to achieve a certain goal. Keeping things simple while looking out for alternative solutions can contribute to leaner, faster, and more maintainable code.

Don’t Repeat Yourself

Pending more detail in this article: Don’t repeat yourself.

Do Not Use Presentational Markup

Avoid Presentational HTML Elements and Attributes

Presentational elements and attributes—for which there’s enough data to prove that they’re popular—make maintenance harder as they violate separation of concerns: They mix document structure and presentation.

For example, the use of font elements or layout tables can require to update possibly hundreds of documents or dozens of templates for something that could otherwise be done by updating a single style sheet.

Remember: HTML changes are expensive.

Avoid Presentational ID and Class Names

Presentational ID and class names represent the same problem, but are something that is fully under control of the author.

Recommendations for advisable ID and class names include:

Keep use of IDs and classes to a minimum.
Use functional ID and class names.
Otherwise: Use generic ID and class names.
In general: Use names that are as short as possible but as long as necessary.

Link Only One Style Sheet and Script File Out of Documents

One generally needs to link at least one style sheet and script out of the HTML of documents or templates to achieve separation of concerns. Any more style sheets or scripts—which appears popular, as sample data suggests—increase the likelihood of HTML changes. This likelihood must not be big, but it’s avoidable.

Use Functional or Generic Style Sheet and Script Names

A poor choice of style sheet and script names, at least of those that are linked directly out of HTML documents, does also unnecessarily increase the probability of changes. It’s best to stick to functional (for example, product.css) or generic names (default.css) to eliminate the risk of those changes, and thus to improve maintainability.

Names like style.css (every style sheet contains “styles,” and so does the next style sheet needed for whatever reason), screen.css (why would anyone want to update x documents just because projection rules have been added to such a style sheet), or standard-v3.css (what if standard-v2.css will continued to be used) are examples for a poor choice of naming.

Do Not Specify Media Types in the Markup

Media types should not be defined in HTML documents and templates, they should instead be defined within style sheets.

Instead of

<link rel="stylesheet" href="standard.css" media="screen, print">

use

<link rel="stylesheet" href="standard.css">

and use @import or @media rules to be able to manage media types in just one spot:

@media screen {}
@media print {}

The reason, again, is minimizing the risk of changes. Changing HTML documents to update media types means change that is avoidable.

In Complex Projects, Use Prefixes

When dealing with more than maybe 200 different ID or class names, ID and class names should be “protected” by a prefix, or “pseudo-namespace.” Prefixes lower the risk of naming and thus layout conflicts, and can make maintenance easier by improving understandability.

For instance, when working in a complex project, use something like “project-classname” instead of “classname”, where “project” represents maybe a 2–3 letter abbreviation of project, feature, or widget, followed by a functional or generic class name.

Adhere to Formatting Styleguides

Agreeing to a certain style of formatting can help maintainability by improving understandability for teams working on the same system, site, or application.

Make Reasonable Use of Comments

Use of comments can make maintenance easier, assuming they aid code comprehension. Especially for less common solutions, comments can be helpful, so make reasonable use of comments to help other people—and maybe your later self—to understand what the code in question solves, and why it solves it the given way.

Update (January 24, 2018)

Also note the extended edition of this guide.

About Me

I’m Jens (long: Jens Oliver Meiert), and I’m a web developer, manager, and author. I’ve worked as a technical lead and engineering manager for small and large enterprises, I’m an occasional contributor to web standards (like HTML, CSS, WCAG), and I write and review books for O’Reilly and Frontend Dogma.

I love trying things, not only in web development and engineering management, but also in other areas like philosophy. Here on meiert.com I share some of my experiences and views. (I value you being critical, interpreting charitably, and giving feedback.)