Technical Debt

Avoiding Technical Debt: Building Code You Can Maintain

martin horn Blog Leave a Comment


Imagine for a moment your organization needs to expand its web properties. Maybe you need a new CMS to support content marketing initiatives or need to build user support forums for a new product line. Maybe you need to be able to spin up new SEM landing pages quickly and easily in response to new initiatives from your marketing department. If you’re a smaller organization without dedicated product managers, who can bridge the gap between non-technical management and developers? And if you do have product managers, or are one, how do you know the developers you are hiring are up to the task?

It’s tough to find good help these days

Software development can be difficult

Building software is hard. There’s no way around it. From the simplest static website to huge web-based applications, building software that works and is usable requires specialized skills that only come with training and practice. And the demand for these skills shows no sign of slowing, which means that hiring good developers is expensive.

That’s why it’s especially important to ask the right questions of prospective developers right from the start.

when “if it works, it works” doesn’t work…

On the surface, it seems like a simple problem.

You want a website. A mobile app. Or a SaaS (software-as-a-service) application. You’ve got a budget to develop it. And either it works, or it doesn’t work, right? As with any talent scouting operation, you should simply be able to look at a developer’s portfolio, check out the applications they’ve created and read their case studies, right?

If the sites work, load quickly, and offer a clean user-experience, that’s great. But what about what’s going on under the hood? If it works it works, and the innards don’t matter, right?

Well, as you probably expected, it’s not that simple.

Technology needs to be nurtured


Do you garden? Even if you don’t, you know that your work doesn’t stop after you plant seeds. You have to water, weed and prune for the entire lifecycle of the plant, if you want it to continue returning yield. Technology is similar. Even the simplest websites will require periodic backups, security updates, bug-fixes and compatibility updates. But perhaps more fundamentally, as your technology drives more and more business your way, your business needs are going to evolve. You might need to add new features and integrate new third-party tools into your technology.

That’s why you want to build technology that is scalable, and extensible from the outset. And you should apply the principle of scalability and extensibility to your human resourcing as well. If you’re working with a development vendor, be sure to fully understand what kind of medium and longer-term support services they offer, and where their roles and responsibilities begin & end vis-a-vis your internal team or other potential vendors. The importance of support services gets amplified when dealing with apps or SaaS.

You have to ask yourself, can your code-base grow with you

It’s important to recognize that as your business grows your business objectives will inevitably pivot or change. Before investing a chunk of change into tech-development, you have to know if your infrastructure will be able to grow with you, to pivot with your evolving needs, and what kind (ballpark) of resourcing will it take? If, for example, you build your website on a platform that simply cannot integrate e-commerce tools that work properly on mobile, and over time your analytics tell you that more and more people are visiting your site via mobile and unable to complete their transactions, well, then you’ve got to start over.

If, on the other hand, you’ve built your site to be extensible, then you’re not starting from scratch, and it’s going to cost you far far less and be live much more quickly.

It’s Called Code Maintainability


What you’re looking for is code maintainability. Which veteran programmer (and occasional Fractal collaborator) Cody Redmond describes as:

cody“The practice of writing modular, cohesive and loosely coupled code that is testable and tested. Code produced in this way is dramatically easier to work with, ensuring faster development cycles, less bugs, and generally improving the quality of a product from end-to-end.”

While a lay person is not going to be able to determine by looking at code whether or not it satisfies these criteria, it’s important to ask questions and get written commitments about documentation and testing right at the outset of any engagement with a developer.

It’s About Limiting Technical Debt
Technical Debt

photo Michael Mayer, cc

Good code is all about eliminating “technical debt.” There are many overlapping definitions of technical debt, but generally speaking it refers to bugs that receive band aid solutions so that the product can ship, and adding new features added without thought to modularity and testability.

Both of these things mean that it becomes harder in the future to manage changes in functionality and to keep the software updated and secure. Instead of carefully adding new features in such a way as to preserve the structural integrity of the original code, new features are added in ways that are easy at the time but done without thought to future requirements. “Bugs become harder to find, shipping of new features crawls to a halt,” says Redmond. “Like any other debt, technical debt accumulates interest, and this interest is the inability to move swiftly and implement changes when it becomes most important.”

Be Transparent, Expect Transparency

It’s important that in your processes you incorporate transparency about goals and work completed. In a larger organization where you may have a product manager interfacing between management and developers, agile development, which is based around development milestones and feature implementations as opposed to deadlines, provides a framework for transparent reporting.

Nic Boshart, loyalty and engagement manager at, and a product manager with years experience building digital properties put it this way:

nicboshart“I’m a big fan of agile [a popular development methodology], and I think small development increments create a more transparent environment, and [make it] easier to show others what’s happening and where you’ve come from. Every development project can be broken down into understandable milestones, and these can be kept on track using project management tools, such as Trello. Having a line into the development’s communication, being able to read their notes around development, all this can help get a sense of what’s happening. If you don’t understand something, ask questions.”

In short, agile provides clear milestones, developer accountability, and visible signs of progress for management.

Understand Scope

Before embarking on any development project it is absolutely critical that the scope is clear. This means that every feature needs to be clearly defined, and not only should you be able to clearly articulate these requirements, after working through them with the developer you hire, they should be able to echo these requirements back to you in a working document that both parties sign off on before the engagement begins.

How should your e-commerce site work? What kinds of payment methods will you accept? How will you add new products to your catalogue? Don’t assume that the answers to these questions are obvious either to you or your developer until they’re written down. Ultimately, if you can’t be crystal clear about what you want (either because you don’t have the words, or more likely because you haven’t yet thought about it yourself) your developer is not going to know either, and the end result is not going to look like or work the way you had envisioned.

Once that scope is established, it becomes possible to break the work down into manageable chunks and your developer should be able to keep you apprised of those milestones. “I have learned the hard way,” says Boshart, “that scope – be it technical capabilities or time to finish projects – is very difficult to manage. Even without being a developer, you at least have to have a concept of how development works, how fast it should take to make something, and how knowledgeable and efficient your development team is, and what priority you are to them. On either side, the onus is on you to communicate effectively what you need done and when you need it done.”

In practice, this means you’re at a disadvantage if you’re a smaller company trying to find good IT or development services without anyone on staff who at least understands the basics of how development works. There are questions you can ask, aside from setting out really clear requirements in the scoping process described above.

Cody Redmond has a series of questions he makes sure he can answer for his clients, and urges very strongly that when looking to have software built your developers should be able to answer them:

6 Questions You Need To Ask Your Developers To Avoid Technical Debt
Question #1

“Is the backend software using a vetted, tested open-source framework, or is it a proprietary solution? Proprietary solutions are typically going to be much more costly to maintain as systems built with well-known and well-supported open-source frameworks such as Django (Python), Rails (Ruby), Play (Scala), or Laravel (PHP).”

Why Ask This Question?

Vendors will sometimes want to sell you proprietary solutions. While the software itself could be great, you’ll have a much harder time finding developers to work on it later whereas open source frameworks such as the ones Redmond mentions benefit from a large community of developers around the world, making it much easier to find someone to help. Proprietary frameworks are also sometimes used by vendors way to lock you their clients into a maintenance contract they may not want or find satisfactory.

Question #2

“Is the core custom functionality unit-tested? Any custom business logic should be bullet-proof in its implementation, and as such should come with it’s own suite of unit-tests.”

Why Ask This Question?

This is a tough one for non-tech people to vet. Your best bet is to opt to have is written into the contract if it isn’t already. Basically, unit-testing ensures that the core components (or modules) that make up your infrastructure can perform their operations properly and independently. When you’re scaling up or adding new features you need to know that these core units are working, otherwise, if things break it will be difficult to ascertain why.

Question #3

“What kind of training, documentation and support can be expected as part of the deliverables for the project? Is the Vendor willing to supply an example up front?”

Why Ask This Question?

This is critical. If you’re receiving a new content management system, for example, you need to be sure you and your staff are up to speed on how to use it. Same goes for adding products to an ecommerce site, or moderating user support forums.

Question #4

“What post-deployment services does the vendor provide? At what cost?”
Is the vendor going to be there when your site gets hacked? (yes, this does happen). And will they be willing to fix the bugs that inevitably come up, even if it’s a year after launch?’

Why Ask This Question?

In an ideal world, you want your technology maintained by the people who developed it. Even if you’re rolling everything in-house, you’ll still want to maintain a connection to your developers as there may be nuances in the way they code that they would be best equipped to troubleshoot. Also, when shopping for development vendors, put nearly as much emphasis in their maintenance services as you do their development services. A developer that charges a premium for initial development but offers a reasonable annual maintenance and upgrade plan might be a better choice that someone who charges half as much for initial development but charges a-la-carte for all post-deployment services.

Question #5

“Who owns the source code, you or the vendor? Are you free to look at it? Are you free to hire other freelancers to work on it? How easy will it be to find other developers?”

Why Ask This Question?

If your contract doesn’t specify that the code that makes up your site or your app belongs to you, this can open up all kinds of problems down the road if you are not satisfied with the support offered by your original vendor.

Question #6

“Does the vendor have the resources to properly support ongoing agile development relationship with you? Do they require that work must be scheduled months in advance? Is it enough for you to be able to respond to outside forces?”

Why Ask This Question?

If you need to make a sudden change to your site, app or SaaS and your developer has lead times of 6 months, you could be left holding the bag. Be sure they will be able to respond quickly, and are open to other developers working on new features if they themselves are unavailable. In a situation like this, documentation becomes very important. How are others supposed to work on your site if they don’t know how it works. More to the point, how are the original developers supposed to remember how it works a year later if they don’t have any documentation?

There Are No Rockstars. There is no magic.

A lot of the problems we’ve discussed can be solved by making sure you’re going with open-source frameworks, and going with developers who have a clear customer-service orientation. A cult of the rock star programmer has emerged in the last few years, fuelled by the idea that there are certain individuals who bring a special skill or magic to the process of development that translates to faster results and better work. But software isn’t magic, and many of the skills that will get you to your goals in software development are the same ones that work in any business environment, namely conscientiousness, good communication skills, and a firm grasp of industry best-practices. Finding a developer who can echo these values back to you is really more than half the battle.


– Martin

Flowering Plant

Leave a Reply

Your email address will not be published. Required fields are marked *