Maintainability Guide

Published on June 17, 2009 (↻ February 5, 2024), filed under Development (RSS feed for all categories).

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

Jens Oliver Meiert, on November 9, 2024.

I’m Jens (long: Jens Oliver Meiert), and I’m a frontend engineering leader and tech author/publisher. I’ve worked as a technical lead for companies like Google and as an engineering manager for companies like Miro, I’m a contributor to several web standards, 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. (Please be critical, interpret charitably, and give feedback.)

Comments (Closed)

On June 18, 2009, 8:41 CEST, Francesco said:
Thanks a lot for the helpful guide!

I also think that you gave lucid explanations and examples for the various techniques and recommendations. All in all a great resource to refer to.

Looking forward to the final version of the guide! 😊
On June 18, 2009, 10:10 CEST, Samuel said:
Concerning not to specify media types in the markup:

In large projects im used to keep all my print styles in a separate stylesheet.

But since “@import url(”print.css”) print;” lacks wide browser support i´ve discovered it is still best practise to specify one general stylesheet for all mediatypes in my markup, and another for print styles only (to override the general CSS where neccesary).

If anyone got a better idea im glad to hear it 😊
On June 20, 2009, 20:52 CEST, Jens Oliver Meiert said:
Samuel—I’m not sure if it’s true that there are still problems around @import and media types, however you can always use @media, as in @media print {}.
On July 1, 2009, 18:34 CEST, Mike said:
Your example for “Keep Things Simple: Use Only What Is Absolutely Necessary”
could itself be a little simpler - there is no need to mix up the concepts of class and ID in this case, better to illustrate with a class on the parent as well as the children, or perhaps by using ID’s on all of the elements.
Newbies often struggle over when to use an ID compared to using a class. As it stands, you example appears to be saying this is one of those times, but actually that is not the lesson you are trying to teach.
On July 1, 2009, 23:34 CEST, Jason Grant said:
I fully agree with these guidelines.

There are loads more to consider for web development, but these are excellent for maintainability considerations.
On July 3, 2009, 7:25 CEST, Andrey Stefanenko said:
>Link Only One Style Sheet and Script File out of Your Documents

Found it a little bit problematic, from multiple device [using site] perspective.

Its about media=”handheld” hook
On September 8, 2009, 13:58 CEST, Amber Weinberg said:
Nice article. I’ve also found it easier in the long run to update websites and code, when the code is as short and simple as possible.