The Compact Guide to Web Maintainability: 200 Tips and Resources
Post from January 24, 2018 (↻ December 5, 2021), filed under Web Development.
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.
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
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).
Refactor when possible.
Be smart—but not too smart.
If necessary, enforce maintenance.
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 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.
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.
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
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 CSS, know when to use
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).
Write semantic HTML.
Use principles across projects (“so it’s easy to switch between them”).
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”).
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”).
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.
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 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.
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.
Sunset unused and unmaintained third-party tools.
Sometimes, don’t use tools.
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 in the future’”).
Refer to official documentation.
Focus on quality.
Maintain proper code hygiene.
Review all code.
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.
Particular resources mentioned in the original maintainability survey.
- A Product Manager’s Guide to Technical Debt
- C# Coding Conventions (C# Programming Guide)
- Government Communications
- Digital Ocean API
- How to Manage a Live WordPress Website Like a Pro
- Meteor API
- PHP Standards Recommendations
- Style Guide Guide
- WPMU DEV
- A List Apart
- Every Page Is Page One
- Frontend Focus
- heise online
- The Interconnected
- IT Hare
- Smashing Magazine
- Stack Overflow
- Web Designer News
- Working Draft
- John Allsopp
- Paul Boag
- Wes Bos
- Chris Coyier
- Anna Debenham
- Martin Fowler
- Jeremy Keith
- Ethan Marcotte
- Robert C. Martin
- Tom McFarlin
- Jens Oliver Meiert
- Eric Meyer
- Harry Roberts
- Matt Stauffer
- David Walsh
Companies and Organizations
- DNN Software
- GOV.UK Blogs
- Nielsen Norman Group
- Pattern Lab
- World Wide Web Consortium
- (A Book Apart)
- The Checklist Manifesto (Atul Gawande)
- Content Strategy for the Web (Kristina Halvorson and Melissa Rach)
- Enduring CSS (Ben Frain)
- Frontend Architecture for Design Systems (Micah Godbolt)
- How to Make Sense of Any Mess (Abby Covert)
- Managing Chaos (Lisa Welchman)
- Scalable and Modular Architecture for CSS (Jonathan Snook)
- (An Event Apart)
- (Meetups, in general)
- (Talks, in general)
Many thanks to the people contributing to the survey.
I’m Jens, and I’m an engineering lead—currently manager for Developer Experience at LivePerson—and author. I’ve worked as a technical lead for Google, I’m close to W3C and WHATWG, and I write and review books for O’Reilly. I love trying things, sometimes including philosophy, art, and adventure. Here on meiert.com I share some of my views and experiences.
If you have a question or suggestion about what I write, please leave a comment (if available) or a message. Thank you!
Have a look at the most popular posts, possibly including:
Looking for a way to comment? Comments have been disabled, unfortunately.
Get a good look at web development? Try The Web Development Glossary (2020). With explanations and definitions for literally thousands of terms from Web Development and related fields, building on Wikipedia as well as the MDN Web Docs. Available at Apple Books, Kobo, Google Play Books, and Leanpub.