The Value of Writing Maintainable Code

This post was originally posted on the Filament Creative blog here.

Something that I’ve felt has been a constant struggle to communicate to clients is how important the quality of their code is. How do you measure, let alone describe the quality of code? What I tend to say is that good code is maintainable.

Unless you decide to take down your website or stop paying your hosting fees, your site or app will live indefinitely. It’s a company’s 24 / 7 open storefront, marketing outlet and support channel. A good website provides a lot of value to a company and if it is to stay online for months or years to come, you’re going to want to make sure it is maintainable.

What is Maintainable Code?

It’s difficult to talk about maintainable code without first talking a little about technical debt. Techopedia describes technical debt as “the implied cost of additional rework caused by choosing an easy solution now instead of using a better approach that would take longer.” It’s important to note that technical debt is a result of the decisions we make over time and in fact, the debt compounds “interest” with each shortcut we take. Some of the more common, high-level causes of technical debt that business owners should be aware of are:

• Insufficient definition
  Business requirements are still being defined while in production
• Market pressure
  The product is delivered prematurely to meet a deadline
• Lack of understanding
  Decisions are made without the proper considerations
• Lack of collaboration
  Knowledge isn’t shared across the team
• Lack of ownership
  When outsourced code needs to be refactored in-house
• Poor technical leadership
  When bad advice is dispersed across the chain of command
• Last minute changes

Some other causes are more low level and deal more with how developers write the code. They include:

• Tightly coupled components
  Code isn’t flexible or modular enough to adapt to evolving business requirements
• Lack of testing suite
  Encourages quick “band-aid” fixes
• Lack of documentation
• Parallel development
  Working in isolation for long periods of time accrues technical debt as the work will eventually need to be merged into the master codebase
• Delayed refactoring
  Code that is meant to be refactored at launch but is untouched and pushed out to a later date
• Lack of standards
  When obscure frameworks or plugins are used in place of more common ones that the team is familiar with
• Lack of knowledge
  When the code is simply poorly written

Writing maintainable code is the best way we can reduce, pay off and ultimately eliminate our technical debt.

When done properly, it looks a little like this: a developer that has never seen the code before, or even the same developer that wrote it returns to the codebase after years of not working with it — is able to gloss over some documentation, install whatever dependencies they require and get up and running fairly quickly. After having the project running in a local environment, they should be able to look through some of the code and get a decent understanding of what systems are in place so that they can modify or extend existing features and deploy them with relative ease.

While the advantages of writing maintainable code directly benefit the developer working on the project, they actually benefit the client far more, albeit indirectly. Let’s unpack that a little bit.

Client Benefits

Maintaining a website is a lot like maintaining a house. A house is always there for you, serving it’s purpose: housing your belongings, hosting visitors and, in a way, representing your interests in some kind of visual form. But as we all know, a house requires work every now and then. You may want to rearrange it, renovate it or maybe even tear some of it down to build something entirely new. You’ll add to it, modify it, update it and ultimately improve it. Throughout its lifetime, a house can become more useful, more convenient, more entertaining, bigger and just overall better. Of course, all of this comes with a cost — it takes a lot of effort, time and money to achieve all of that, and thus owning a house is a real investment. The same is true for a website, app or any kind of digital property.

Adding New Features

Technical debt catches up to you when you’re trying to make improvements. Using the house analogy, we can see how adding a new feature to a site or app may reveal some unknown obstacles and costs had the project not been maintained properly.

Let’s say a couple purchases a bungalow and after a few years, they have a child together. They decide they need an upgrade. They absolutely love the neighborhood they’re in and are overall quite happy with their current home. The backyard is perfect and the interior is all new. They just need a little more room, so they decide to add a second floor. They consult Google, make some phone calls, and finally estimate out all the costs of what they think is required to add an additional floor. Their contractor shows up to inspect the house and suddenly their entire plan is put into jeopardy.

After only minutes of inspection, the contractor learns that the foundation of the house is unsuitable to support a second floor. Adding the second floor is simply not an option until the foundation is repaired in some cases, torn down and rebuilt. These kind of jobs require an understanding of the existing foundation, which as the contractor points out, is somewhat unusual and particularly difficult to navigate. The contractor says they can do it but it will take much longer than originally anticipated, moving the completion date later than expected, and worse, the estimate has now ballooned to almost double what the couple had originally thought it would be.

This kind of unexpected increase in timeline and budget tends to happen when a house or website was either not built well from the start or poorly maintained over time, but writing maintainable code can help mitigate these kinds of issues.

Upgrading

Similar to adding a new feature, upgrading or relocating an existing one can also reveal some unforeseen obstacles and costs associated with the foundation and maintenance of your website or app.

Back to the house. After paying those unforeseen costs and the second floor is finally installed, the couple decides they want to replace their television on the main floor with a new one that has BluRay and HDMI. They therefore have to move the one they currently have upstairs or just get rid of it. They decide to keep the television, however, they quickly realize moving it anywhere may be more challenging than they originally anticipated. Although the television they bought years ago was a flat screen, it wasn’t an LCD. It was an old tube television that weighs 300lbs.

At the time, it was the latest technology. It displayed a massive, great looking picture, had all the nifty features for recording shows and keeping favourite channels. It even included a built-in DVD player! But unfortunately, it was too heavy and extremely difficult to move. Just moving it upstairs would be its own project, so the couple hires some movers to do it for them.

Having to pay someone to move the old television wasn’t something the couple had in mind when they were thinking of upgrading their TV with those newer features, but it was a necessary cost, though one I’m sure the couple would rather do without had the television been a little more manageable.

A piece of furniture and likewise, a piece of code, benefits from being modular in the sense that you can quickly and easily move it, rearrange it, extend it or remove it. Otherwise, if the furniture is big, bloated and really quite difficult to fix, move, or extend, it makes relocating it and sometimes upgrading it that much more difficult.

Regressions

Sometimes when you add, modify or upgrade a feature of your website or app, a new bug is introduced. We call these bugs regressions. Regressions can cause further technical debt if not dealt with and properly maintained.

Upon the movers leaving, the couple notices that one of the movers had scratched the glass surface of one their paintings on the stairwell. Not a big deal they think, until they bring it into the shop and realize the glass costs a fortune to repair because you know, the sizing of the frame is custom. So the couple adds it to the list and their budget again increases unexpectedly.

Upgrades inevitably come with the risk of introducing a new bug. If the code is difficult to move or extend, there will be a greater risk of having an effect on the other features it comes into contact with, which may produce their own unforeseen challenges and costs. Once again, writing maintainable code can help prevent that or at the very least, offer a way to remedy the issue easily and quickly.

A Quick Recap

When adding a new feature or upgrading an existing one on a project that has not been properly maintained, just finding someone to take on the job might prove difficult (they don’t want your technical debt) and whoever is employed for the job will no doubt struggle to complete it, as we saw with the couple with their second floor addition and new television.

Writing maintainable code will allow developers and more importantly, our clients, to improve a project long term, but it’s important to recognize that it will add some time and cost to development up front and is something to consider in your initial estimates. Maintainable code isn’t something that can really be seen holistically or assessed very easily, which is why it can be difficult to convey the value in it, but make no mistake — writing maintainable code is what will elevate your company’s presence for a long time to come. Invest in maintainable code and give the care your company’s digital products deserve.