Maintainability Guide (Beta)

Jens O. Meiert, June 17, 2009 / August 3, 2009.

This entry is filed under Web Development.

This documentation on maintenance and maintainability means a start. I’ve been focusing a lot on these topics over the last few weeks, maybe a bit longer, so it’s been about time to share some beef, and to still, all of a sudden, double the documentation that’s out there.

Index

Introduction
1. Definition
2. Assumptions
Characteristics of Maintainability
Techniques and Recommendations

Introduction

Maintainability is important in order to deal with change. Good maintainability makes change easier yet avoids change that is not necessary, and good maintainability also makes change more affordable.

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” (via Jeremy D. Miller).

Other definitions conclude: “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

A few assumptions can be made to help understanding of maintainability:

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.
Change is inevitable, yet there is avoidable change.
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-explaining” or commented so that everyone involved in the development can understand what the code does.

Separation of Concerns and Orthogonality

To achieve easier maintainability concerns have to be separated, which means to break a 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 the system.”

Extensibility

A maintainable system is not just understandable and separates concerns, it’s also extensible. This means, that it is made 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

This list is work in progress.

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 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 wouldn’t need a result class. You could use the context instead: #results li.

What’s more, 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 immensely to leaner, faster, and more maintainable code.

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 presentation with document structure.

For example, the use of font elements or layout tables will force you to update maybe hundreds of documents or dozens of templates for something that could otherwise just 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 very same problem, but are something that is fully under control of the author/developer.

Recommendations for advisable ID and class names include:

Keep use of IDs and classes to a minimum.
Use functional ID and class names.
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 Your Documents

In most cases, you have to link 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 is quite popular, as data samples suggest –, however, just 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 more expensive changes without good reason. 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 will the next style sheet you might need due to whatever reason), screen.css (why would you want to update x documents just because you add projection rules to that style sheet, too?), 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 “Pseudo-Namespaces”

When dealing with more than maybe 200 different ID or class names, ID and class names should be “protected” by a prefix, a pseudo-namespace. Pseudo-namespaces 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 within teams working on the same system, site, or application.

Make Reasonable Use of Comments

Supporting understandability, use of comments can make maintenance easier. Especially for less common problems, comments will 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.

Enjoy the most popular posts, probably including:

Comments

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 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 7, 2009, 20:23 CEST, Jens Meiert said:

This post is also available in German.
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.

Jens Meiert