Take the 2-minute tour ×
Programmers Stack Exchange is a question and answer site for professional programmers interested in conceptual questions about software development. It's 100% free, no registration required.

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

share|improve this question
    
If the stakeholders don't believe your estimates, maybe you should suggest they get a second opinion. –  kevin cline Feb 29 '12 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 Feb 29 '12 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 Mar 1 '12 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. –  Martin Brown Mar 8 '12 at 15:23
add comment

4 Answers 4

up vote 6 down vote accepted

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.

share|improve this answer
add comment

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

share|improve this answer
2  
Awesome analogy! I'll have to borrow that one. It's really easy to picture. –  jmort253 Mar 1 '12 at 2:55
1  
Yeah, but who wants to eat uncooked spaghetti? –  Karl Bielefeldt Mar 1 '12 at 13:15
    
@KarlBielefeldt - indeed, I'd compare spaghetti to ravioli. –  Joris Timmermans Mar 8 '12 at 15:36
add comment

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.

share|improve this answer
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 Mar 1 '12 at 14:19
add comment

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.

share|improve this answer
    
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 Mar 1 '12 at 14:21
add comment

Your Answer

 
discard

By posting your answer, you agree to the privacy policy and terms of service.

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