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 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?

share|improve this question

migrated from stackoverflow.com Mar 19 '11 at 3:24

This question came from our site for professional and enthusiast programmers.

7  
Can we please stop using the term code smells? It makes me gag in my mouth a little every time I hear it. Thanks, yours truly. –  Joe Philllips Nov 26 '08 at 15:42
2  
Actually I can't say the term appeals to me either, but since its such a widely used term its a convenient way to communicate an important part of this question. "smells" aren't necessarily "defects" or even "issues", they just.... smell bad? –  Ed Guiness Nov 26 '08 at 17:05

16 Answers 16

I think you could get some fine points from the book Beautiful Architecture, chapter two A Tale of Two Systems: A Modern-Day Software Fable

The problems within the Metropolis spilled out from the codebase to cause havoc elsewhere in the company. There were problems in the development team, but the architectural rot also affected the people supporting and using the product.

The development team

New recruits coming into the project (like myself) were stunned by the complexity and were unable to come to grips with what was going on. This partially explains why very few new recruits stayed at the company for any length of time—staff turnover was very high. Those who remained had to work very hard, and stress levels on the project were high. Planning new features instilled a dread fear.

Slow development cycle

Since maintaining the Metropolis was a frightful task, even simple changes or “small” bug fixes took an unpredictable length of time. Managing the software development cycle was difficult, timescales were hard to plan, and the release cycle was cumbersome and slow. Customers were left waiting for important features, and management got increasingly frustrated at the development team’s inability to meet business requirements.

Support engineers

The product support engineers had an awful time trying to support a flaky product while working out the intricate behavioral differences between relatively minor software releases.

share|improve this answer

It is unusual for the results of a code review to go to a non-technical audience. But if you have to:

Can you relate the kind of problems in maintainability you found to existing maintainability problems they have already experienced? For instance can you say, that fixing X now will prevent Y from happening just like it did with the XYZ report problem we had last month. Perhaps you can find some cases in your own company where bad code led to really expensive fixes ("It will take 6 weeks and ten developers to fix that") or problems that people just have to live with now ("Yeah I know it takes 30 minutes to run that report, but to fix it we would have to redesign the database from scratch and rewrite all our code") because the fix is too expensive. If you have some local problems that were especially painful, those are great for analogies as to why this particular code should be fixed now. Remind them of the pain of fixing problems after going to prod when customers are screaming and things that must work simply don't (or don't work fast enough). These are pains the non-technical users have felt. You want them to understand the code review is trying to help avoid them in the future. IF you can find the cost per bug and how it increases depending on the project phase in which it is fixed, then make sure to have that with you.

IF some of your fixes are due to known performance issues of certain techniques (like using a cursor in SQL Server), it may help to show a small example of the bad technique and an improved one so they can see the performance increase when using the better techinique. (This doesn't mean fix all the bad code, just create a smaple of a bad technique and a good techinque to show show why it is bad from the user perspective. Remember, performance is much more critical to users than to anyone else. They will get the point more easily than developers will. I did this once to show why we had to get rid of a cursor in a trigger (shudder!) and one small demo that it took me 15 minutes max to write showed why the poor techique was a problem and I got immediate approval of the hours to do the fix on existing code that works just fine. Plus a small demo like this can give them confidence that you know what you are talking about and will make it easier for them to accept the other changes you have as well.

share|improve this answer

Technical Debt

I've wrote about on my blog some time ago :

"Technical debt" is the mess you make when you take shortcuts while developing software.

It's a very powerful concept and it's easy to explain it to anyone with the basic understanding in taking loans, even without any technical background (for example, management).

When you do something the quick and dirty way, instead of the right way, you take on technical debt, every time you have to do something with that code it's now going to take longer because its badly designed (just like interest payments) and you should sometime re-write the offending code (pay off the debt) and that will take more time than writing it write to begin with (more interest).

Just like financial debt, when used wisely, let's you spend now money you'll only have later – at a (sometimes considerable) cost, technical dept let you get something done quickly and the cost is more work down the road. Also just like financial debt, when you take on more technical debt then you have the ability to pay off (either due to bad planning or without noticing) your product is doomed.

Here is an article by Steve McConnell that describes technical debt better then I'm able to.

share|improve this answer

Bob Martin told this story at Agile 2008 (and it might be in his Clean Code: A Handbook of Agile Software Craftsmanship 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.

share|improve this answer

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.
share|improve this answer

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.

share|improve this answer

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.

share|improve this answer

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?

share|improve this answer

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.
share|improve this answer

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.

share|improve this answer

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.

share|improve this answer

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.

share|improve this answer

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.

share|improve this answer

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.
share|improve this answer

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.

share|improve this answer

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.

share|improve this answer

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.