I'm in search of good language or metaphors to discuss the maintainability of code with non-technical folks (PMs, business sponsors &c).

In particular, I've recently created a few one-off, get-it-done-tonight, gets-the-job-done pieces of code. Everyone, including the internal sponsor, knew that we were saving a couple hours based on the premise that the code would be used once, for the immediate need, and not again.

Then the inevitable: "Hey, remember that thing we did? Let's do it again, but with these minor changes." Of course, the minor changes aren't so minor, all the more so because the code was written as a big ol' procedural nastiness hinging on assumptions about the environment. [Yes, yes, I know, avoid the problem in the first place. Don't write bad code. Write everything as if it will be maintained by someone else, or me years from now. That's a different question, though. This is after it's happened.]

So what are some good metaphors for the internal sponsor (non-technical) to quickly explain why the code isn't maintenance or minor-change friendly? The walls on a movie set: There's no garage there, it's just a door. -or- The doors are welded shut on this car.

How do you describe this continuum?

I want to find some terms for our group that will help talk about how much effort goes in up front and how that will improve maintainability: illustrating the trade-offs in "Do you want this tonight or do you want it maintainable?"

(In writing this up, I realize this might be the same as defining 'maintainable' for non-technical stakeholders. Seems like explaining loose coupling to non-technical types may not be the best way out of this. If you've successfully done that, how?)

Edited for answer: For now I will continue to use building construction metaphors. This will turn into the size and strength of the foundation: "Yes we can build that building on this, but we will need to rework the foundation to be larger and cover the right area."

  • If the stakeholders don't believe your estimates, maybe you should suggest they get a second opinion. Commented Feb 29, 2012 at 23:04
  • The stakeholders believe my estimates: I'm looking for a way to elaborate on the statement: "Remember, we thought this would only be used once. It won't be easy to alter it for this use."
    – Jamie F
    Commented Feb 29, 2012 at 23:10
  • You've gone down the wrong path. Now you have to go back to where you started because in this business, there are few short-cuts.
    – JeffO
    Commented Mar 1, 2012 at 0:39
  • @kevin: Getting people to get second oppinions is often a bad idea as they normally end up getting someone who says 'Yes I could do that in 5 minutes' because they don't know what is involved, know they will never be held to account and frankly don't care. Commented Mar 8, 2012 at 15:23

4 Answers 4


Construction metaphors are often helpful when explaining software concepts to non-technical folks.

You can say, for example, "This code was so jury-rigged, it was like using a 2x4 to prop open the garage door instead of installing a proper garage door opener."

Construction metaphors lend themselves nicely to a continuum of explanations.


Here try this, works for my students all the time :)

Take a pack of spaghetti to the meeting (uncooked) and ask them to remove a single noodle or multiple ones. It's easy.

Now take a cooked one or just 'dump the uncooked ones' on the table and ask them to pick something without disturbing the surroundings (or in case of the cooked one, trace it's start/end).

This usually hits the point home: The uncooked spaghetti is well architected, separation of concerns, clean and takes effort discipline to make it (think of the manufacturing process).

The latter, just dump in a pan to cook or on the table, quick to do but a nightmare to sift through later.

Hence the term 'spaghetti code' :)

  • 2
    Awesome analogy! I'll have to borrow that one. It's really easy to picture.
    – jmort253
    Commented Mar 1, 2012 at 2:55
  • 1
    Yeah, but who wants to eat uncooked spaghetti? Commented Mar 1, 2012 at 13:15
  • @KarlBielefeldt - indeed, I'd compare spaghetti to ravioli. Commented Mar 8, 2012 at 15:36

Think of everyday objects with well-defined interfaces that make it easily replaceable, like a light bulb or battery. Explain that the very first electric lights Edison built didn't have nice screw-in bulbs, because it was faster just to wire the bulb directly when designing it than to spend extra time designing a screw-in socket. Sockets were developed later when bulbs had to be replaced frequently.

Software's the same. There are ways to "directly wire" some things in that make it faster up front to develop, but also make it harder to replace parts of it. If you want to make a lot of changes later on, first you have to design the "screw-in socket," then the rest will be quicker and easier to change.

  • 1
    +1, I like this a lot: it doesn't have the same perjorative on the early work; the hardwired light bulb was a reasonable choice at the time, but it hinders options later.
    – Jamie F
    Commented Mar 1, 2012 at 14:19

I would talk in terms of "technical debt" for this, especially if talking to stakeholders like customers or managers that have an ear for concerns of finance. Making bad decisions or generating sloppy work is like taking out loans that have interest rates.

  • For software that is known to be long lived when it starts out, then this works well. It falls apart when the one-time conversion utility suddenly changes from being one-off to multiple use. Money has a relatively constant value...
    – Jamie F
    Commented Mar 1, 2012 at 14:21

Not the answer you're looking for? Browse other questions tagged or ask your own question.