How to measure maintainability

Every in-house developer has said it at least once: "I don't want to touch that module, I'm not sure what will break." Every CEO has heard the finance team complain that a "quick fix" in the order system took three weeks instead of three days. Every IT manager has watched a simple feature request turn into a multi-sprint archaeology project just to understand how the existing code even works.

Those are all symptoms of the same underlying problem: low maintainability. The trouble is that most companies only notice maintainability when it's already gone — nobody schedules a check-up for it the way they schedule a server backup or a security audit. This article gives you a concrete way to measure maintainability before it becomes a crisis, so you can decide whether your system needs a tune-up, a refactor, or a rebuild.

This builds on our broader piece on how to keep business software maintainable as it grows — if that article is the "why it matters," this one is the "how do I actually check."

What does "maintainability" actually mean?

Maintainability is the ease with which a system can be understood, modified, extended, and fixed — by someone who is not necessarily the person who originally built it. It is not the same as "the software works." A system can run perfectly fine in production today and still be almost unmaintainable, because nobody besides one developer (who might leave next month) understands how it fits together.

A useful mental test: if your lead developer got hit by a bus tomorrow, could a competent replacement understand the order-processing module well enough to safely change it within a week? If the honest answer is "no, it would take months," you have a maintainability problem, regardless of how smoothly the software runs right now.

Why can't you just "feel" whether software is maintainable?

Because gut feeling is unreliable in both directions. A system built five years ago in an outdated tool can still be highly maintainable if it was structured cleanly, documented, and kept modular. Meanwhile, a system built last year on the latest stack can already be a tangled mess if shortcuts were taken under deadline pressure.

We've seen this in FileMaker projects specifically: a 15-year-old solution with consistent naming conventions, clear script folders, and one data model diagram on the wall is often easier to extend than a two-year-old system with 40 layouts named "Layout 2 copy," scripts triggered from six different places, and business logic buried inside layout calculations. Age is not the signal. Structure is.

What concrete metrics can you use to measure maintainability?

You don't need an academic software-engineering framework to get real signal. These five practical measurements work well for custom business software, including FileMaker solutions, ERPs, and connected systems:

1. Time-to-first-safe-change. Give a developer who has never touched the system a small, well-defined change request (e.g., "add a discount field to the invoice screen"). Time how long it takes them to make that change without breaking anything else. Days is healthy; weeks is a warning sign.
2. Change failure rate. Of the last 20 changes deployed, how many caused a bug, a support ticket, or a rollback within two weeks? Above roughly 15-20% suggests the system's structure isn't protecting you from unintended side effects.
3. Dependency density. Pick one core table or module (e.g., the customer record). Count how many other scripts, layouts, or external integrations directly depend on its exact current structure. The higher the number, the more fragile any change to that module becomes — this is often where FileMaker solutions get brittle, because a layout, a script, and an API connector can all silently depend on the same field name.
4. Documentation coverage. What percentage of business-critical scripts, workflows, or API endpoints have even a one-paragraph explanation of what they do and why? Zero documentation isn't automatically fatal for a small system, but it becomes a serious liability once the team grows past two developers.
5. Onboarding time. How long does it take a new developer to become productive — able to ship a real, non-trivial change with a mentor's review but without hand-holding? Two weeks is good for most mid-sized systems; three months is a red flag.

How do you turn these metrics into a real answer?

Measuring one of these in isolation tells you little. The pattern across all five is what matters. A system with a fast time-to-first-safe-change but sky-high dependency density might look maintainable today and become unmaintainable the moment you add your third integration. A system with excellent documentation but a high change failure rate suggests the documentation describes intent, not reality — which is almost worse than no documentation at all, because it actively misleads people.

A practical way to run this as a quarterly or annual check:

• Pick 3-5 representative modules or workflows (not the whole system at once).
• Score each on the five metrics above, even roughly (green/yellow/red is fine to start).
• Look for repeated red flags across modules — that's your real risk area, not the one loud complaint from last week's support ticket.
• Compare the score to the same exercise six or twelve months earlier, if you have one. Trend matters more than any single snapshot.

Does the platform or tooling change how you measure this?

The metrics stay the same, but where the risk hides changes depending on your platform.

In FileMaker, maintainability risk often concentrates in a few specific places: business logic scattered across layout calculations instead of centralized scripts, scripts triggered from multiple places with no single source of truth, and naming conventions that drift as different developers touch the file over the years. Dependency density (metric 3) is usually the most revealing check in a FileMaker system, because FileMaker makes it very easy to reference a field or script from many places without any compiler warning you when that reference breaks.

In systems that have started layering AI-assisted development into the workflow — using tools like Claude or similar AI coding assistants to generate scripts, suggest refactors, or write documentation — maintainability measurement gets an extra wrinkle worth watching. AI-generated code can look clean and well-commented while quietly introducing patterns that don't match the rest of the codebase, or duplicating logic that already exists elsewhere in the system. Treat AI-assisted changes as a distinct category in your change failure rate tracking, at least for the first few months, so you can see whether they're actually helping maintainability or just producing more code, faster, that someone still has to maintain.

If you've modernized the interface layer — for example using a tool like FM BetterForms to give a FileMaker back end a more modern, responsive web-style front end — measure the UI and the back end separately. A beautiful new interface can mask (or even worsen) back-end maintainability problems if the underlying data model and scripts weren't cleaned up at the same time. We've seen teams do a UI refresh, feel a wave of relief because everything "looks" modern, and then discover eighteen months later that the same tangled scripts from before are still there, just wearing a nicer front end.

What should you do once you know your maintainability score is low?

Knowing the number is only useful if it changes a decision. A few honest next steps depending on what you find:

• High dependency density in one module, everything else fine → isolate and refactor that one module before it becomes the bottleneck for every future feature.
• Low documentation coverage but low change failure rate → you're probably fine short-term, but you're one key-person departure away from a crisis. Start documenting the highest-traffic workflows first.
• High change failure rate across the board → this usually isn't a code problem, it's a process problem. Look at whether changes get reviewed and tested before deployment, not just at the code itself.
• Long onboarding time → this is often the earliest reliable warning sign of a system that's becoming a black box, even before bugs start showing up in production.

FAQ: measuring software maintainability

How often should we measure maintainability? Once a year at minimum for stable systems; quarterly if you're actively growing the team, adding integrations, or shipping frequent changes.

Can we measure maintainability without a dedicated tool? Yes. The five metrics above can be tracked in a spreadsheet. The discipline of measuring consistently matters far more than the sophistication of the tool.

Is a maintainability score the same as code quality? No. Code can be technically clean and still be hard to maintain if nobody understands why it was written that way, or if it's tightly coupled to systems that change independently. Maintainability is about the whole system and the team's relationship to it, not just the code itself.

Does switching platforms automatically improve maintainability? No — and this is one of the more expensive misconceptions we see. A rebuild on a new platform inherits every undocumented business rule and unclear requirement from the old system, unless someone deliberately captures and cleans those up during the migration. Platform choice matters less than structure, documentation, and process.

A quick checklist before your next maintainability review

• Have we timed how long a small, real change takes for someone unfamiliar with the module?
• Do we know our change failure rate for the last 20 deployments?
• Have we mapped which scripts, layouts, or integrations depend on our most-used tables or fields?
• Is there at least a one-paragraph explanation for every business-critical workflow?
• Do we know how long it currently takes a new developer to ship their first real change?
• If we're using AI-assisted coding, are we tracking its changes separately in our failure rate?
• If we've modernized the UI, have we checked the back end separately for hidden debt?

If this check-up surfaces more red flags than green ones, that's not a verdict that everything needs to be rebuilt — it's a starting point for a focused conversation. Loggix regularly helps teams run exactly this kind of maintainability assessment on custom FileMaker systems, ERPs, and the API integrations connecting them, and from there maps out whether the right next step is a targeted refactor, a smarter use of AI tools inside the existing workflow, a modernized interface layer, or a broader consultancy conversation about where the system needs to go next.