Fighting the Good-Code Fight (Or, ‘We Need To Talk About Tech Debt’)


“What we do in life echoes in eternity…” 

I’ll hazard a guess that “Gen. Maximus Decimus Meridius” (hint: the gladiator in Gladiator) was not thinking about the importance of code quality and documentation when he addressed the above wisdom to his cavalry on the battlefield.

But really, what IT organization wouldn’t benefit from a fictional Roman general showing up before the start of a new project to gravely remind everyone about lasting consequences? After all, the decisions you make in code design today will affect your organization for months – or years – into the future.

To wit, I began working at the Learning Lab about a month ago and I’m just beginning to grasp the astounding amount of technical debt that surrounds us here from coding past. We’ve done our best to document the myriad of convoluted processes that dated design decisions have heaped upon us, but these limping hulks of code still consume our time, drain our energy, and foment our collective frustration in ways that the original designers could not have possibly envisioned (I hope).

This is the cost of design decisions on future productivity – a cost paid for down the road, and sometimes at quite a heavy price. Bad design decisions eventually lead to increased support requirements (from the developer and for the end-user), the inability to adopt new technologies/frameworks (or react to security issues, for that matter), and generally prove to be an overall drain on employee morale.

Tech debt is a huge topic, I know – far too much discussion for one post – so today just I’ll focus just on how technical debt becomes an insidious force in your IT organization.



Before we go any further I should note that some technical debt is inevitable. No developer or IT team will ever be effective enough to avoid any and all technical debt; rather, the idea is to be vigilant in managing tech projects in order to ameliorate the threat as much as possible. Good planning and good code help minimize it. But in the face of impending deadlines we can’t always be perfect, and the oft-resulting “paralysis by analysis” is just as harmful to productivity as being bogged down by a mess of technical debt.  


[Spoiler Alert: The enemy is time.]

Any developer worth their salt knows that “good code” is code that is tested thoroughly (through automated and usability tests), in addition to being well-documented and easily maintained (e.g., upgradable, the ability to add on features, and so on). Basically, from a management perspective, we want our developers to utilize the standards of their specific language of choice to deliver the good stuff. And yet, the accrual of bad technical debt still runs rampant in IT organizations both large and small. Why is that?  

It’s because what we want and the time it takes to actually do it right are often mutually exclusive. In a fantasy world we’d all have open-ended deadlines, unlimited expertise, and ample resources – vanquishing technical debt before it can gain any ground. The real world isn’t nearly that, well, fantastical, and in the battle between delivering a good, sustainable product and a finite amount of turnaround time, technical debt is invariably unleashed.

Given that the spectre of this debt threat first takes hold during the initial planning of a project – before the first line of code is even written – project managers and developers should work closely together to formalize realistic timelines for deliverables. “Fantasy” timeframes lead to corner-cutting, not to mention the hackneyed solutions that “we’ll fix later” (which almost never happens), and (inevitably) a regrettable lack of documentation and/or testing

The responsibility for this crucial coordination rests equally on the shoulders of project managers and developers: The latter need to be frank with regard to their respective skill levels and current task loads, while the former need to advocate for the developers and be covetous (or at least duly aware) of the finite amount of resources available for a given job.

This is all to say that working out an agreed upon, written-out timeline all parties are comfortable with is the first step to avoiding technical debt.  



Any project devoid of a deliberate and well-documented development model is as vulnerable to racking up technical debt as a project with an unrealistic timeline. I won’t get into specific models or procedures, but it’s important to realize that thoughtful planning on how you proceed with a development project is paramount in the war against the insidious tyrant of tech debt.

A solid strategic approach to implementing a structured pathway from idea to deliverable involves issue tracking, establishing standards for documentation and testing, consistently adhering to front-end and back-end frameworks, and creating avenues for client feedback. This clearly communicated “structure” allows for uniform code – otherwise, a lack of agreed-upon standards and processes allows individual developers to be siloed into their own personal set of design ideas (which, more often than not, leads to inconsistent code and a lack of documentation).  

In essence, the first step to understanding and thereby avoiding technical debt is to think through the overall development process long before a new project even crosses your desk. And then, before you signal your team to “unleash hell,” foster a candid dialogue between developers and project managers with the goal of cementing a timeline that’s realistic for both parties, ensuring your project’s victory (i.e., good code delivered within the prescribed timeline) with an arsenal of operational policies and procedures geared toward defeating technical debt once and for all (or at last until the next project)…


~by Joe LeeSenior Technical Project Manager for the Learning Lab team.