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

migration rejected from stackoverflow.com Nov 3 at 9:28

This question came from our site for professional and enthusiast programmers. Votes, comments, and answers are locked due to the question being closed here, but it may be eligible for editing and reopening on the site where it originated.

closed as primarily opinion-based by gnat, MichaelT, GlenH7, Dan Pichelman, Kilian Foth Nov 3 at 9:28

Many good questions generate some degree of opinion based on expert experience, but answers to this question will tend to be almost entirely based on opinions, rather than facts, references, or specific expertise.If this question can be reworded to fit the rules in the help center, please edit the question.

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

2 Answers 2

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

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

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