The Compact Guide to Web Maintainability: 200 Tips and Resources

Published on January 24, 2018 (↻ February 5, 2024), filed under Development (RSS feed for all categories).

Half a year ago I was happy to work with A List Apart to ask our field a few questions about maintainability: What helps website maintenance? What prevents it? And what resources do developers turn to for improving maintainability?

The goal was to get a much more in-depth and a much more practical view than what we had before, which was little more than a few theses put up about a decade earlier. The result was a list of 134 responses with more than 500 data points that have now all been reviewed, normalized, rephrased, sorted, and tested, to form a new guide, a new and more definite guide to web maintainability.

To elaborate on each point would have meant a whole book on the topic; and while I like the idea of indeed making it another one (or see someone else write one), I’ve opted to first present it in a form that’s easier to scan and digest. Categorization was not always trivial, and some redundancy may exist, too, but with your and the field’s help—comment here or send a message—we can improve and build on this so to accomplish an actual base to work on when it comes to: maintenance, and maintainability.

Aleta tidies up her kingdom like a good housewife.

Figure: Maintaining a kingdom, not nearly as politically correct as we maintain code bases. (Copyright King Features Syndicate, Inc., distr. Bulls.)

The following uses the words “maintenance” and “maintainability” quite liberally. As one may suspect, “maintenance” refers to the act of maintaining, “maintainability” to the ease (or even possibility) of a code base to be maintained. Also, then: Exceptions prove the rule. Sometimes it depends, and personally I don’t agree with each and every single statement in here, either. And, finally: This post contains more than 200 statements and resources, and yet not enough.

The 9 Pillars of Maintainability
Resources

The 9 Pillars of Maintainability

There are roughly nine parts to maintenance and maintainability.

For the markup connaisseur, all aspects are laid out in sentence and paragraph form to add weight to them. Like other posts on this site, this post will also be updated, and perhaps amended by examples, in order to keep it relevant for time to come.

Be Clear About Maintenance

Understand the value of maintainability and maintenance.

See the big picture (and avoid getting caught up in details).

Avoid unnecessary changes. “Change is inevitable, yet there is change that is avoidable.” (This we know for many years.)

Take or define ownership. Avoid interference by outsiders.

Set aside a budget for maintenance.

Make sure to build and hire maintenance competence and expertise.

Define processes and procedures.

Offer motivation and incentives to maintain.

Make maintenance a priority.

Avoid “big bang” maintenance, when everything has to be updated at the same time.

Set clear maintenance goals and direction.

Beware of slowness (“changing direction ~~[…]~~ takes nearly forever to saturate, resulting in many layers of partial changes—aka lava flow”).

Assign and delegate maintenance responsibilities. Avoid unclear responsibilities. Avoid “too many cooks in the kitchen.” Reassign unengaged content owners.

Rotate the team (over the code base).

Set reminders (for updates and maintenance).

Don’t procrastinate.

Refactor when possible.

Be smart—but not too smart.

If necessary, enforce maintenance.

Plan

Understand organization and project. Internalize mission and purpose. Comprehend needs and necessities.

Know all the priorities.

Focus. Avoid scope and feature creep.

Beware of expectations of the wrong people—for example, HTML skills from users or CMS editors.

Structure the work; avoid chaos and disorganisation.

Define site concepts and goals.

Look for a balance.

Consider each project’s lifespan. Think about the future: “How can I write this in a way that a developer five years from now will understand it?”

Set up care and maintenance plans.

Allow for enough time for maintenance.

Work off technical debt.

Talk about maintainability of features specifically, upfront.

Prepare for complexity.

Prepare for aging issues (“the more mature a project becomes the bigger the problems caused by poor [or] no longer fit for purpose decisions”).

Do It Yourself

Avoid outsourcing (“~~[…]~~ and expecting the internal team to just ‘figure out’ how to keep the collection of scope creep and cutting-corners ~~[…]~~ from catching fire and burning to the ground”).

Write code from scratch where possible—or tailor.

Avoid (“if something is able to be coded, code it”) or make minimal use of plugins and third-party “boilerplates.”

Limit use of third-party tools (to avoid support and security issues).

Avoid customization of third-party tools.

But: Don’t improvise; avoid temporary fixes to turn permanent.

Keep It Simple

Use only what’s absolutely necessary.

Prefer simplicity over flexibility. (Use your own judgment.)

Avoid overzealous, “pixel-perfect” design (and too much CSS in consequence).

Be clear and consistent.

Avoid content and code excesses.

Avoid repetition.

Beware of exceptions and special cases (for example, CMS inputs for custom markup). But: Avoid early consolidation and abstraction (only “until you have at least three or four usages,” because “a bad abstraction is much harder to maintain than no abstraction”).

Write human-readable code, then use a build step to optimize it.

Adhere to Standards and Best Practices

Work disciplined. Don’t be sloppy.

Don’t become too pragmatic. Don’t always take the easy way. Avoid “copy and paste” coding. Avoid “updates through appending.” Avoid short-term fixes.

Be consistent.

Keep dependencies to a minimum, and particularly avoid complex and hidden dependencies. Avoid high code coupling.

Use (and break websites up into) reusable components and modules.

Structure the code. Keep all structure descriptive: Use useful nomenclatures and naming, link only one style sheet and script file, use functional or generic style sheet and script names. In HTML, keep nesting reasonable; do not specify media types in the markup.

Keep logic as clean as possible (for example, avoid nested ifs).

Separate concerns (especially CSS in JavaScript). Don’t use inline CSS or JavaScript.

In CSS, be aware of the implications of broad selectors.

Use normalized databases (“using databases where you can easily insert/update data instead of changing code means you won’t have to change code later”).

Use uni-directional data-flow (instead of mutating global state).

Be aware of “invisible” conventions and standards (for example, with WCAG).

Use coding conventions (style guide) and coding standards (code consistency). Use consistent indentation and nesting.

Use naming conventions.

In JavaScript, beware of long functions, use short ones (with few parameters).

In CSS, know when to use !important.

Be careful about global event listeners and global selectors.

Follow professional standards and practices. Apply the Single Responsibility Principle. Use Test-Driven Development (TDD). Use Object-Oriented Programming (OOP). Apply PHP Standards Recommendations (PSR). Use namespaces. Use immediately-invoked function expressions (IIFE).

Don’t Repeat Yourself (DRY).

Write semantic HTML.

Lint CSS and JavaScript.

Use principles across projects (“so it’s easy to switch between them”).

Run backups.

Maintain inventory.

Use the boyscout rule (à la “leave things better than you found them,” and “always check a module in cleaner than when you checked it out,” per Robert C. Martin).

Avoid mystery code (“coders who purposely make it hard to read their work, perhaps thinking they will make themselves indispensable”).

Use Processes

Communicate, especially during the design phase (“the single biggest detriment to maintainability ~~[…]~~ is winning the argument that tech debt &c. is as important as feature development”).

Make use of Continuous Integration (CI).

Establish and enforce principles and standards (like, “be diligent in what you add and generous in what you take off”).

Establish routines.

Code in tandem.

Organize code as if it was under public review and scrutiny (like an open source project).

Use Agile methodology.

Test (for regressions), but avoid unreasonable testing needs. Include critical devices.

Set up and follow maintenance and update routines.

Automate.

Know and Use Your Tools

Use quality tools.

Use off-the-shelf technology (for easier ramp-up and easier help). But, use only well-supported third-party software; avoid exotic, esoteric, undocumented tools and methods; avoid overreliance on third-party tools; avoid new technology for the sake of new technology.

Use a version/source control system.

Use a content management system (CMS).

Use a JavaScript framework (to stay focused and avoid anti-patterns). But, use reusable libraries that are easily extensible.

Use a component-based system. Pair scripts to style sheets 1:1.

Use a preprocessor (like Sass or LESS).

Use a package manager (which can list outdated packages) and package management tools.

Use build tools (to automate).

Use a dependency manager.

Use a pattern library with a grid and type system for code and design patterns.

Use templates.

Avoid dependence on systems that offer no staging or QA environment.

Understand the tools. Be conscious about tool changes (“the best tool is often the one in your hand”).

Understand the system architecture.

Disable (unneeded) features.

Update, regularly.

Sunset unused and unmaintained third-party tools.

Sometimes, don’t use tools.

Document

Talk about what is done and why.

Document, detailed and understandable, in-line and in-file. Document architecture; work and prior work; updates and versions; decisions; standard operating procedures.

Comment the code (“leave little notes for ‘yourself [and your peers] in the future’”).

Refer to official documentation.

Review

Focus on quality.

Maintain proper code hygiene.

Review all code.

Log.

Monitor. Monitor the code base, especially unused code (code rot). Monitor performance. Monitor tools, and avoid tools that aren’t needed. Monitor everything.

Audit regularly. Run quality checks. Take samples, to check for quality issues. Check for broken links. Audit everything.

Resources

Particular resources mentioned in the original maintainability survey.

Articles &c.

Magazines &c.

People

Companies and Organizations

Books

Events

(An Event Apart)
(Meetups, in general)
(Talks, in general)

Many thanks to the people contributing to the survey.

About Me

Jens Oliver Meiert, on November 9, 2024.

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 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. (I value you being critical, interpreting charitably, and giving feedback.)