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

Change has a cost, and that cost is the motivation to improve maintainability.

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

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

Do Not Use Presentational Markup

Avoid Presentational HTML Elements and Attributes

Presentational elements and attributes—for which there are enough numbers to prove that they are quite 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 force you to update maybe 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.

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 Your Documents

You generally need to link at least one style sheet and script out of the HTML of your 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 increase the probability of changes for nothing. 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.

So 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 very complex project, use something like “project-classname” instead of “classname”, where “project” represents maybe a 2-3 letter abbreviation of your 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, given they help understanding. 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.

About the Author

If you have any questions or concerns about what he writes, ask him to explain, or share your own position by sending a constructive comment or email. (And, if you think something could be of interest to Jens, recommendations for excellent literature are always welcome.)

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

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.