Part II: Practical Examples of Paying Down Technical Debt


Technical Debt Vicious Cycle

Technical Debt exists in many forms. Perhaps the most common concerns software maintainability. Code that is difficult to maintain is more expensive to maintain, plus the development group can’t respond to the business as quickly. So, we can then conclude that code that is poorly-written or difficult-to-read costs the company money – directly or indirectly.

Coding Best Practices Virtuous Cycle

Why Care?
The typical argument that is made is “Don’t worry about it, *I* can read the code and that’s all the matters!” This is incorrect for a few important reasons. Unless you are writing software for your own company, you are not writing your code. You are being paid to write code for Company X. Company X is the owner of that code. Company X wants, and has the right to have its code written in the best manner possible, so that developers can roll-on and roll-off the project quickly. Professional code that adheres to time-tested, industry-standard best-practices is what I mean when I say “best manner possible”, by the way.

The company hires a professional to do a proper, professional job. This is the same way that you hire a mechanic to fix your car properly or how you might hire an architect to design a house that doesn’t fall down. You have an expectation that they are going to follow best-practices and do the best, professional job they can, right? I’m not accusing anyone of not being professional – I’m just pointing out that there is actually a proper way to write code!

FxCop and Framework Design Guidelines:
When it comes to naming standards for example, Framework Design Guidelines already lays this out for us. If you are programming on the .NET platform, regardless of language, you should follow those naming standards. In addition, FxCop or the integrated static code analysis in Visual Studio analyze your code and make recommendations. In fact, many of the rules that FxCop enforces, came from Framework Design Guidelines.

If you have never used FxCop – I highly recommend you do. I promise you, FxCop will make you a better developer. The first time you run it, it is going to come back with 1000 warning messages. If you take the time, and start digging into them, more times than not (perhaps 98% of the time), FxCop brings up a good point that should be addressed. You’ll also find that most of those messages are repeats, because of repeated violations in code.

Pretty code isn’t just about looks…
The added benefit of good naming is that if you are a developer that can write good, readable code, that is what makes you valuable to the company. The idea of “they can’t fire me, no one else can read this code!” will only keep you employed long enough for them to find someone else who can read your code, and then refactor it into something better.

The other argument that is commonly made is that “I just don’t think about it, I have a deadline on Friday – who cares how *pretty* the code is?” You should care. This isn’t about “pretty” code it’s about writing code that is easy to read, and therefore easy (read: fast and cheap) to update. This is to everyone’s benefit!

I have had the privilege of doing many, many code reviews in my career. You learn a lot from doing a code review. As you review someone’s code, it should hopefully teach you things and make you reconsider techniques in your own code.

For example, whenever I have to look at VB.NET code, 9 times out of 10, it was code that was migrated from VB6 and earlier. That means it typically looks like this (in C# below, to more clearly make the point):

Technical Debt Coding Best Practice

Without XML code comments, without strong-typing, and without good variable names – I wonder what this method does?

Technical Debt Coding Best Practices

Looking at the ProcDoc method above – what is so wrong with doing things that way? After all, a vast majority of code is written that way. It’s not so much an issue of whether that code will work; the issue is how well and how easy that code is to maintain.

The code above has no exception handling, poorly-named variables, no XML code comments, and is weakly typed. All of these contribute to several unhandled exceptions that will occur at run-time, and code that is not particularly easy to read. Specifically, it’s more confusing than it has to be or should be.

It took maybe 2 minutes to write the code above. It took about 2 minutes and 30 seconds to re-write the method properly, below:

Technical Debt Coding Best Practices

So, for very little effort, we simply gave variables good names, stayed as strongly-typed for long as possible (note the use of Int32 and the Boolean) – and this results in very easy code to read and understand. This was not a huge effort, by any stretch of the imagination. You can’t give me the excuse of “who has time to waste on making the code *pretty*?” This simply isn’t true, professional code does not take a long time to write.

The added benefit isn’t just for the future developer that will have to maintain this code – the benefit is to the consuming developer too (which might be a different group). Look at our intellisense now!

Technical Debt coding Best Practices

Technical Debt Best Practices

Intellisense gives us all kinds of information now! I didn’t have time to wrap that SqlException and throw my own custom exception, so I merely published that we let that exception bubble up. Maybe we can dig in and refactor that next time. For now though, I am making that method as proper as I reasonably can. That’s that point.

One common thing I see is that we developers sometimes approach this problem as an all-of-nothing proposition. We either write proper code that is well-documented –or– we will just keep adding on the bailing wire and duct tape. In reality though, that’s not a great choice. If we just get in the habit of writing proper, production code all the time – this problem won’t exist!

Technical debt in the example above was that developers chose to make ProdDoc(o) poorly written so that they could slam out some release. As we know, that was a very mild example. However, if you have a whole class, and then a whole library full of things like ProcDoc(o) – next thing you know, you have a mess. You have a code base that is expensive and slow to update because it is poorly written. Put another way, that time that was “saved” by writing it fast-and-bad – you now pay interest on it every single time you have to go back in. Whenever possible, make a point to choose fast-and-good, it truly is not much more effort.

Read Part I of Practical Examples of Paying Down Technical Debt

Filed in: Technical Debt
Load more reviews
Thank you for the review! Your review must be approved first
You've already submitted a review for this item