How do you go about explaining refactoring (and technical debt) to a non-technical person (typically a PHB or customer)? ("What, it's going to cost me a month of your work with no visible difference?!")

UPDATE Thanks for all the answers so far, I think this list will provide several useful analogies to which we can point the appropriate people (though editing out references to PHBs may be wise!)

Not the best analogy because it makes it sound like bad stuff just spontaneously crawls into your theater, as oppose to the bad stuff appearing as a direct result of continuously building your theater.
–
doppelgreenerNov 10 '10 at 7:29

17

@Axidos: "rats nest" is an English idiom that means "a seemingly impossible to undo tangle" (in this case, of cords and cables behind the entertainment center)
–
HedgeMageNov 10 '10 at 8:08

@Peter: I think we've all had to go behind the TV at least once though. Just explain it as a hundred times worse and spin a yarn of cables everywhere and pull this and pull that and discover a dead civilisation somewhere in the mess.
–
doppelgreenerNov 10 '10 at 13:22

I wouldn't explain the concept of technical debt, because it's not necessary. Instead, focus on refactoring: You are changing the design of your program, not necessarily so that it is "better" or "improved," you are changing it so that it can accept a change that you need to make.

A car analogy might fit: You need to add an air-conditioner to a car, but it wasn't originally designed for one. Not only do you have to make a weird L-shaped air-conditioner, but you also need to move some other things out of the way first and change the venting system.

I also think it's a better strategy to refactor when you are accommodating new features: otherwise you might be changing the design into something that only looks "better," but might actually be poorly suited to the circumstances surrounding the addition of your next feature.

I like this one because it emphasizes that the refactoring is being done to make a required change easier (or possible). Refactoring should usually not be done for its own sake, but to meet a specific goal.
–
Kristopher JohnsonDec 9 '10 at 18:58

I would say ”code maintenance”. It's important to use words that the non-technical person is familiar with and that make sense to a non-technical world view.
If non-technical person (customer) is familiar with application maintenance then it's easy to make parallel of code maintenance and application maintenance. Even if they are not the same, you can explain that the end customer here are developers or those how maintain the system.

Non technical people are familar with application maintenance? I asked my grandmother: she isn't ans she is the most non technical person i found. Additionally: Since a non technical person doen't know the difference between code and application ("If the code is the application, the application is code") your analogy won't work.
–
MartinNov 10 '10 at 9:18

1

in the places I've worked, the marketing and projman types have understood "maintenance" to mean "bug fixes after release", and it'd be disingenuous to claim that refactoring is fixing bugs.
–
user4051Nov 10 '10 at 11:07

"Have you ever played Mouse Trap? As we stick in new features, change interfaces, and fix bugs, code can start to look a lot like that. There comes a point where we either have to expend a lot of capital (time and effort, which amount to money) making sure all the moving parts play nicely with each new change or addition, or we can instead set time aside to refactor the design, resulting in fewer moving parts we have to manage each time we make a change. It may seem, from an end-user's perspective, that the refactor doesn't have any benefits, but the benefit happens every time a new feature is added post-refactor. The process is faster, introduces fewer bugs, and is less expensive thereafter, not to mention that the refactored code is often more efficient overall.

You may wonder why we let it start to look like Mouse Trap in the first place:

Sometimes getting something done right now means that we have to sacrifice elegance and efficiency to just "make it work".

The language features and other technologies available to us as programmers often change. Sometimes new features let us replace a finnicky jumble of six moving parts with one.

Oftentimes, when we add feature C to features A and B, we don't know that B will eventually be dropped and D added. One way to accomplish C may work very well with B, but not very well with D.

In an effort to keep building a better mouse trap, we have to constantly go back and find places to reduce complexity and streamline what we have. It's the difference between just having software with a lot of features, and having truly high-quality software."

Hello
I haven't really thought it out but it is similar to when you build a house in small steps. Add a room, add another floor and after some time bearing walls are deep inside the construction. The floor is not at the same height, etc. The plumbing system is all over the house.

Then you need to consolidate the space and rebuild walls, make more efficient plumbing and so forth to make more convenient to use the spaces to different purposes.

Something along these lines.

The advantages is that this metaphor works because most people have experiences of being inside a house.

All the analogies to things in the physical world -- like building a theater -- are, IMO, terrible.

You need to explain that refactoring code is like... refactoring code. Software is malleable in ways that physical analogs are not. As things get more and more complex, one must reactor (or redo, as you wish) massive or small parts of a codebase so that we can continue to increase the complexity without going insane.

Why do we refactor? Because code that is never refactored costs more per minute to maintain and change, and ultimately becomes more problematic.

What's so interesting about refactoring is that we redo the codebase but, at least at the outset, the functionality remains the same.

You aren't doing any modifications to the house. You're just shifting stuff around and getting rid of some of the dust. Maybe throwing some things out that you don't use or need anymore. but you're not adding anything.

I use the term Technical Debt and relate it directly to something they understand - Corporate Debt. Technical Debt is like taking out a loan. You pay interest on it. E.g., you can build a new factory and pay for it outright or you can get a loan for it. If you get a loan you will actually pay more for it in the long term, but it makes sense financially if the terms are right.

However, if you are paying 25% interest on such a loan you put yourself into a non-sustainable position. This is the same with technical debt. Sometimes it makes sense to take on some technical debt. However, there comes a point where the interest is too high and it needs to be paid off. Some techincal debt is like a home loan and some it is like credit card debt. In emergencies credit card debt is an important and valuable asset. However, it can also break the bank (or household if you choose) if used unwisely.

Another example: you can pay $10,000 for a marketing mail drop to garner more leads for sales in the future. You are paying off "sales debt". This is an expense with long term payoff. Equate this to why you would want to "spend" money now refactoring a piece of code. In both cases there is no immediate payoff, but you are setting yourself up for better performance in the future.

I tend to use the term "xxxx debt" as an analogy when talking to whomever the target audience is. E.g., Operational Debt - The printing press we have now works well, but by stopping production for one day (or one week) and upgrading to a new machine we can increase output by 25%.

+1 for a well reasoned reply that demonstrates realistic economics. Debt is rational at times, and purists miss too many opportunities if they cannot tolerate it.
–
MacneilNov 10 '10 at 18:01

1

And people understand that taking out loans to pay the interest on older loans is not sustainable.
–
Christopher MahanNov 11 '10 at 1:38

1

This is my preference for explanation, because I like to refer to scrapping everything and rewriting (which often is the only option left due to so much technical debt) as technical bankruptcy
–
Wayne MDec 5 '11 at 13:11

3

This is a terrible answer. (1) This is more complicated than the technical explanation of refactoring. (2) This doesn't explain the "why"s of refactoring; it explains the "when"s of refactoring (ie: when it is cost effective). Or maybe I really just don't understand this post, and hence point (1).
–
Thomas EdingSep 25 '12 at 0:54

2

@ThomasEding (1) This is not an explanation of refactoring, it is an explanation of technical debt. (2) This does explain the why of when to refactor - to a business person. Honestly, they don't care about the technical reason, you do. They want a justifiable reason you are working on something other than the next feature that will drive sales. This is why most programmers can't talk to their boss and complain the boss is stupid. They are not stupid, they just have different drivers than you.
–
NemiSep 26 '12 at 20:03

My biggest worry (hence biggest motivator for re-factoring) at my current company is our reliance on frameworks that are nearing (or have reached) the end of their current life-cycle. Management needs to understand that when a piece of the application is dependent on a framework like Hibernate2, documentation is harder to find, answers on message boards are harder to come by, and developers used to working with newer versions are going to run in circles figuring out how to accomplish tasks that were trivial in newer versions, but barely supported (if at all) in aging versions.

You begin to pay a price for maintaining existing features or developing new ones because common tasks are generally simplified in updated version of framework (Spring, Hibernate, insert your choice here).

Like most infrastructure, if it goes unmaintained, you won't notice trouble until things go horribly wrong (e.g the bridge or road collapses, the pipes burst, you short your electrical supply, etc...). In the case of outdated versions of frameworks, you start to see compatibility issues with application servers, you find it harder to attract development talent, and it takes longer to implement new features.

The costs of leaving a code base "as-is" and attempting to develop new features on top of that base are tangible, and shouldn't be brushed away under the rubric of "so you'll do all this work and I won't see any difference." As an end-user of the application, perhaps not. As a business owner, hiring manager, or team-lead, very much so.

It's kinda like cleaning up the house after a wild and crazy party from the night before.

Let's say the living room got totally trashed. The house is still a house, the living room is still a living room. It works but it's not the way it could be. After staring at the mess you realize that it needs to get cleaned up.

So, you start bagging the trash. It looks better already. So, you look around the room and decide to straighten out the furniture. You put one piece back, then the next and the next. Wow, the room looks really good. You are proud.

Your sister walks in and says the room looks like trash, you should fix the bookshelf and vaccuum the carpet. She's right. The room looks really, really good.

You look around and see that the window shades would look much better if they were all at the same height. Done. Wow, the room is amazing.

Take it with an example ... everyone has in their lives written a letter to a dear one. It has to be someone dear because in those letters we usually pay attention to composition as well.

So, you have your text, ... the meaning will go through either way, but you want the entire thing to sound nice! Right?

Refactoring, same thing ... same pieces of information, more or less, but the composition is better. And it will probably result in a better review by the reader.

Another example - writing an article for a magazine. Two writers, both know "their stuff", the only difference is one knows "how to write" and the other writes like he learned to write from answers like these.

This is a slightly more graphical version of the home theatre analogy.

If you want to add one more new appliance [aka, new functionality], at a pinch you can probably fit it in somewhere.

If you want to add yet another appliance, you can buy an extension lead, which will buy you some time.

But at each addition, it becomes more difficult to find a solution. And you're exposing yourself to a risk1 of fire [aka bugs], and you will have to pull out the big bucks to pay someone to put new sockets into the wall, which could quite possibly escalate all the way up to the main circuit board, or even further.

1 Another thing PHBs don't grok very well: "Well if it only might happen, what are you worrying about?"

Writing software is a lot like writing a big non-fiction book, or an encyclopedia.

The first draft always sucks. It can always be improved by reorganizing it, removing sections that don't need to be there, and ensuring a consistent style throughout.

Whenever you have to revise, the simplest thing to do is just to add a new section, change a few words, and so on. But as the revisions pile up, the book starts to lose its organization. So you have to make further passes of reorganization. If you don't, the book becomes a nonsensical jumble.

Say you are a mechanics that specializes in customizing cars, even building them from scratch if the customer requires it. There is this customer that is back in your shop every so often to always put some new shiny thing in his super-sized limo.

Once he comes in to have a nice sound system installed. You diligently perform the task passing wires and connecting it all properly. He goes out a day later, he is happy and pays handsomely, as usual.

The next month he comes back but this time he wants a full blown home theatre installed. Once again, you take the limo in. Being a professional you revisit the sound system and make it easier to maintain by installing a tubing system for running the wires around the car. This way the wires are protected and easier to pull out and should you need to add more will also be easy to do. So you rip the old wires out, install the tubing and pass the sound system and the extra wires for the cinema, close it all up and you are done.

Realizing that the customer did not ask you to replace the old sound system you scratch off some of the cost of the replacements and of the tubes. However you still make money from the deal, Just not as much as you would have had you just threw the system together like you did the first time.

One month later he comes back, this time he wants a lighting system and he wants new speakers having damaged the old ones earlier in the week.

Because you kept everything nice and tidy you can quickly run the new lighting wires through your tube, install the system and replace the speaker. This time however you are done much faster, the re-factoring paid off by keeping you on top of your game.

Your competitor who was laughing at you for ripping perfectly good wires and installing all this extra tubing is still struggling to get his customer satisfied. Sure he was done faster than you most of the times but as time goes his customers are complaining that there are more and more delays and the overall quality of the work is degrading.

Looking at this you realize that your goal to not only stay in the business but to be the top gun is to balance what you do for filling the customer's demands and what you do to make your life easier down the road. Very rarely a customer will pay for both so you have to manage closely. You gamble that by pro-actively doing things right even at the cost of doing things twice you will keep maintenance costs at a controlled stable percentage of your productivity.

Software is the same, except programmers can play with digital duct tape for a VERY long time before the effects are truly felt by customers and managers. Unfortunately by that time the cost of re-doing things right grows exponentially with respect to how much duct tape is present and the average age of said duct tape.

This is why it is important that we keep re-factoring the system. Very often experience will show us new more efficient way to do the same thing or we can combine similar functionality and exploit redundancies instead of just copy past them. This is how we keep the system lean and mean. Time will show that constantly re-factoring the system to meet demands will keep productivity constant by controlling the amount placed in maintenance.

Placing duct tape will momentarily increase productivity at the cost of carrying a sub-optimal system. Technical debt is incurred whenever immediate productivity is favoured in detriment of the other aspects of a system. The debt analogy is good because just as interests over borrowed capital eat away the profits the borrowed time making things quickly incurs higher maintenance and increase the system fragility forcing a team to spend additional resources in maintaining rather than creating. Just like its financial relative, if the borrowing continues unabated most resources are spent towards interest repayment leaving very little for improvements. Technical debt will eat away technical resources to a point where most resources are spent just keeping the system running grinding to a halt all other possible enhancements.

So ultimately the questions is not should we or should we not do it but is it ethical to let managers and customers believe they can rely on productivity figures artificially bloated with the use of digital duct tape. Some would think it is a business decision but quite frankly this is so just because managers do not understand it. In the end, someone will have to pay the debt either though heavy re-factoring or by migrating to a new system. It is ultimately to us, programmers, to keep systems maintainable, you should not have to ask to re-factor as it is an inherent part of the job, failing to understand this is failing to understand what software engineering is all about. This said, I realize there are systems out there that have incurred an important debt already and paying off this debt will require decisions from the payers. Your job is such situation is to at least do your part to stop borrowing. This debt was incurred BY US maybe because we did not know better, because we were pressured to do it, still, we took on this debt and very often the people we handed the debt to do not understand it, thus cannot manage it properly.

Here's your software, all done, hope you like it.... Ho by the way, I maxed out your credit card doing it, hope you don't mind... cya

I thought of another example, which apparently no-one here has mentioned: refactoring is pretty much exactly the same as rearranging an equation in maths (though that might fall outside the scope of 'non-technical person, I guess).

When you rearrange an equation, you just 'move stuff around' to make it more readable and more usable, without changing the meaning.

Refactoring is a similar concept except instead of simple math equations, you put in algorithms. The main idea is that you can swap between two ways of doing things because they will yield the same result.

The simplest refactoring that can be done is renaming.

doX() { ... }
{
doX()
}

Now because we don't really want things to be called doX because we don't really know what it means, we rename it to something else that is more self explanatory and replace anywhere we have used it.

doBusinessTransaction() { ... }
{
doBusinessTransaction()
}

This will save you money later on when there is a problem or enhancement because it reduces the time for people to understand and fix your application. To further save money, there are free tools that do this work for you automatically depending on what language you are using. These tools are also licensed such that it is not restrictive and would require you to do anything special aside from acknowledging it if you use it directly.

Take your desktop computer for instance. You have a tower, monitor, keyboard, mouse, printer, scanner and speakers. Ultimately all you want is a nice organized desk. So you just plug things in blindly, and a few minutes later, lo and behold, everything is set up the way you want it. Well... almost the way you want it.

A day later when you are changing the balance on your speakers, you realize you accidentally put your left and right speakers in the wrong areas, so you want to swap their positions. But oh no! There is a jungle of tangled cords; when you proceed to move the speakers, your mouse cord gets hooked, and now your mouse gets dragged along with the speakers. Also, your keyboard now doesn't have any slack -- you used to be able to move it from the desk onto your lap.

Alright, you could just unplug the mouse and keyboard and reinsert them so everything is fixed. But this won't help with future reorganization and future additions. Also weaving your mouse and keyboard cords through the jungle is a hassle.

The better solution is to replug everything to plug them back in a neat clean way where each cord does not interfere with another. Now future changes are easy and continue to be easy. You invest a little up front for big gains later.

The key point is that the original solution mostly WORKED. That's the thing about refactoring: it works to begin with, but you need to change how things already exist to easily make future changes (moving the speakers).