Communications regarding maintainability of code [duplicate]

Question

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."

Answer 1

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.

Answer 2

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' :)

Answer 3

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.

Answer 4

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.