Best way to relate code smells to a non technical audience?

Question

I have been asked to present examples of code issues that were found during a code review.

My audience is mostly non-technical and I want to try to express the issues in such a way that I convey the importance of "good code" versus "bad code".

But as I review my presentation it seems to me I've glossed over the reasons why it is important to write good code. I've mentioned a number of reasons including ease of maintenance, increased likelihood of bugs, but with my "non tech" hat on they seem unconvincing.

What is your advice for helping a non-technical audience relate to the importance of good code?

Answer 1

Technical Debt

I've wrote about on my blog some time ago http://www.nbdtech.com/blog/archive/2008/11/02/technical-debt.aspx

Answer 2

I tend to avoid words like "easy" and replace them with "cost effective". If you tell a non-technical audience that messy code is hard to maintain, they are probably thinking "boo hoo". If you tell them it's more expensive, they get the point.

Answer 3

I always do comparison with something they know. Example of building a house rapidly without using good material...etc. This way, they have a mental image of something they know and understand that is less abstract than code.

Answer 4

Try to make a translation of the common concepts:

• Quality (good code has less bugs)
• Maintainability (good code take less time to change than bad code)
• Understandability, (new programmers can understand and work with good code earlier than with bad code).
• Professionality, (you are paid to distinguish between good and bad code).

Then you can use a translation of coding terms:

• Debugging, improving the quality of the code by removing the bugs.
• Refactoring, changing bad code into good code. It is a small investment now, but saves a lot in the future.
• Unit testing, automatically test the code so you know that it still does what it is supposed to do.

Answer 5

Most code smells are indicators of poor code maintainability. I would guess most non-technical people who have been involved with software development understand maintainability. Everyone has seen projects where changes in functionality took longer and longer to implement as the code got more and more complex.

Answer 6

I can understand the feeling that "ease of maintenance" and "increased likelihood of bugs" seem unconvincing when looking at them from a non-technical standpoint, because they are both technical descriptions.

I'd recommend reducing everything to the lowest common denominator: Money.

Different things can cost money, and addressing code smells can reduce or eliminate those costs. Examples:

• Ease of maintenance - If we do this now, it will cost only X fraction of the amount we'll have to spend by letting this continue and being forced to address it later.
• Less likelihood of bugs - Fixing a bug costs X, so if we can reduce the incidence of bugs by Y percent, we are saving money.

If you can relate everything back to time, effort, or the ability to deliver product, then you are talking money, and that's a language non-technical people understand.

Answer 7

try representing the concept of good code vs bad code in picture give him statistic about time taken for maintain good code /bad code then time gained is money gain.

Answer 8

Bob Martin told this story at Agile 2008 (and it might be in his Clean Code book). His example was making dinner. The easiest way to make dinner is to never clean up afterwards. You just leave the dishes unwashed. Next time you want to make dinner, you just find some new dishes and repeat. Pretty soon the dishes you have to work with are not really the ones you want to use, you have to make them work in ways they're not intended to and you don't get what you really want to eat. Eventually, you have to clean everything up. Now it's much harder because everything is crusted on and hard as a rock. Stuff is stuck together and you have to work to break it apart. The alternative is to outsource dinner!

I know I butchered this. Bob Martin is a much better storyteller than I am.

Answer 9

The problem with the house-analogy is that in my experience a house isn't changed as often as code is.

Most of the work done with code is not writing it, but changing, expanding, fixing and refactoring. This should probably be related before the concept of "code smell" would make sense. Or phrased differently: Code smell isn't really a big problem if no one ever needs to read or change the code. As long as it runs, who cares? Right?

So communicating that fact is an important part of making any audience understand code smell.

Answer 10

One thing I have often remembered and used is (I think I got it from Spolsky?) the escalating cost of fixing a bug throughout product life cycle.

When you are developing, a fix takes a tenth of the cost of that same fix when a product is in test. When the product is in test the cost is around a tenth of the cost of when the product has been rolled out. (Well, that was about what I recall anyhow).

The idea is to communicate the idea that the better you get something in the first instance, the better off you are- by a very large factor.

Answer 11

It's not just money but also time that non-tech people value and understand.

So, some ways to explain benefits of good and standards compliant code vs bad code would be:

1. Much lesser time required to extend functionality in future.
2. Parts of it can be easily extracted out and replaced with other solutions in a snap.
3. Less number of operations staff required.
4. More stable and hence better end-user experience.
5. Less time required for new developer to get started.
6. Easy help from developers community leading to less wasted time in trying to resolve issues.
7. Comparatively easier to make strategic changes to project goals.
8. Can reuse the work done into other projects leading to less time to implement similar product lines.

Answer 12

What are the consequences of the issues you've found, in practical terms? Presumably they 1) make it more time-consuming (and thus more expensive) to fix bugs in those areas of the application, and 2) they make it more time-consuming to add new functionality to the application. (there may be more points, of course, depending on the issues you've found, and the codebase and application in general)

How much more time-consuming? If you can't quantify it, how do you expect them to buy your argument?

Duplicated code might, in grossly simplified terms mean that every bugfix takes twice as long (because they have to be fixed in two places, and in each, you need to test to make sure your fix didn't break anything). Code which isn't sufficiently general may have to be rewritten when new features are added, and that introduces a risk of breaking everything around it. How much will that cost?

My best suggestion is going to be to try to put numbers on how much these issues are going to cost down the line. Of course you can't make an accurate estimate, but you're definitely better qualified to come up with a rough guess than your audience is. So that's what you have to do.

Otherwise, you're just asking them to follow your hunch, your irrational instinct. While we'd say your instinct is probably right, it's going to be a hard sell to a non-technical audience. They're likely to say that "if even the programmer can't say how much it'll cost us in the long run if we don't fix these issues, how do we know they're issues at all?"

You might be able to do this by setting up simple scenarios ("Let's say we ignore these issues for now, and at some point after release, a critical bug in component X is found. Because of the messy code we never got around to fixing when we had the chance, this component is now intertwined with components Y and Z, so a fix will have to be tested against this much larger chunk of code to ensure it didn't break existing functionality. This'll take so many days every time a bug in this component is discovered, which could have been reduced to that many days if we fix this issue up front".), or by pulling in generally available statistics (how long does it take to fix bugs in clean vs. messy codebases? Did it pay off for other teams to clean up code smell early?

Answer 13

I would use the house analogy, but talk about it as a house that you know you are going to add rooms on to. If the walls of the house are slightly off perpendicular, and you are never going to add any rooms, it isn't that big of a deal. But if you are going to add rooms, then one of three things is going to happen. 1) Whoever is doing the work on the additional room will have to catch the fact that they are adding on to a wall that is not perpendicular and do extra work to adjust for it. (not likely) 2) Whoever is doing the work doesn't catch the initial problem, but does do a very good job, however because the wall they are going off of is slanted, their walls end up being slanted too.(fairly likely) 3) they do an ok job but end up adding even more slant to the walls(fairly likely). Repeat over the course of several additions and the last room is either a monster pain in the butt to build, or it ends up with walls that are at a 45 degree angle to the ground, which makes it kinda hard to put a bookshelf up against or hang a picture on.

Answer 14

I just thought of another way of helping my audience relate to the problem of poor quality code.

From now on, whenever I fix a bug, I'll check if the bug was attributable to poor code. I expect that very soon I will have compelling statistics that correlate poor quality code to bugs and time spent fixing them.