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

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?

Explanation / 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.

Related Questions

Navigate

• Browse (All)
• Browse I
• Subjects

Integrity-first tutoring: explanations and feedback only — we do not complete graded work. Learn more.