How to explain why design choices are good? [closed]

Question

As I've become a better developer, I find that much of my design skill comes more from intuition than mechanical analysis. This is great. It lets me read code and get a feel for it quicker. It lets me translate designs between languages and abstractions much easier. And it lets me get stuff done faster.

The downside is that I find it harder to explain to teammates (and worse, management) why a particular design is advantageous; especially teammates that are behind the times on best practices. "This design is more testable!" or "You should favor composition over inheritance." go right over their heads, and lead into the rabbit hole of me trying to clue everyone in to the last decade of software engineering advances.

I'll get better at it with practice of course, but in the mean time it involves a lot of wasted time and/or bad design (that will lead to wasted time fixing it later). How can I better explain why a certain design is superior, when the benefits aren't completely obvious to the audience?

Answer 1

This may not directly answer your question, but it might lead you in an interesting direction.

I think what you need to do is more related to selling them on the idea than explaining it to them. Sales is all about understanding what the customer's problem is and then showing them how your product (or development method, whatever) will benefit them. Each person has different needs, so those things that benefit one person and gets them excited may very well leave another person cold.

For your CEO time-to-market may be the key, for your manager it might be more predictable schedules, for your programming colleagues it might be faster coding (or easier testing / documentation / debugging / whatever), and for your company's customers it might be ... ?

Sales does not happen automagically -- you have to make a concerted effort to understand the other person's point of view, and then figure out how to map your ideas into their Happy Place™. Once they know how they will personally benefit from this new thing, they often ask, "How much will it cost and how soon can we do it?" Once you hear those magic words you know you have done your sales job well.

Answer 2

I don't really have a solution to your question but some time ago I've faced exactly the same dilemma and was looking to answer exactly this same question.

I would find myself on one side of the argument and someone else on the other side and even though every fiber of my body told me the right design is X, I could not back it using words.

Worse yet is that sometimes I would concede the point and let the other person implement it their way only to have their design blow up in my face and then I'd think, "Yeah, this is perfect example of why I didn't want to do it that way. If only I could demonstrate this code to them back then."

Well, I never really found the answer but few days ago as I was flipping through Lean Software Development: An Agile Toolkit, I came across something interesting that might suggest that the answer doesn't actually exist. A section of the book was talking about leaders in other fields, especially in emergency response units and how those leaders made decisions. When there's a fire, or someone is shooting at you, those leaders never sit down and argue pros/cons with their teammates. Instead, they use intuition, which was developed through training and experience to help them make decisions. Same applies to our profession: how can you make fully logical decision when faced with a ton of unknowns and variability that is so common in software development? The authors argue that instead of attempting to justify every decisions, developers should be encouraged to train and improve their instincts so eventually they would "just know" what to do.

The only way I found to get past these arguments is to build a proven track record of my work. To show management and others on my team that the design decisions I make in my code result in code that is easier to maintain, extend and is more reliable. You do this repeatedly and people will notice you. At that point, your opinion, which might only be based on your instinct, will have a much higher weight than it does today. This strategy worked with 90%+ of my team including my boss. Unfortunately, you might find one or two guys who are completely stubborn and will refuse to see anything your way. At that point, you have few options:

1. You can try to pull rank (I ended up going to my boss and asking for a rank because I was so tired of these dead-end arguments)
2. You can try to lobby for majority of the team to support you.
3. If the project can afford (i.e not too much loss in productivity), what in your opinion is a bad decision, let the other person win the argument. One of two things will happen:
   • In some cases (hopefully very small portion), your intuition will be wrong and you will end up learning something. Good for you.
   • In most cases (again... hopefully), you AND the person who was advocating "bad" design will realize exactly why it is bad; after all hindsight is always 20/20. Hopefully, this will be a lesson to that person that possibly you know what you are talking about and next time they'll think twice arguing their case.

Answer 3

Well, this answer isn't really as specific to programming as you might think. You have to bring it back to things they do understand.

If it's something like composition over inheritance, you probably just have to say that currently perhaps 90% of developers would consider that a best practice (a wild guess, based partly on the fact that 100% of developers agree on almost nothing), and you agree and would be happy to go into why.

I try to be as honest as I can about what's controversial, and what percentage of developers would agree with me.

This generally works better with management than developers, who probably will make you go down the rabbit hole of explaining whether you are really advocating good design and how do you know it. There is something commendable in this, but it means you must put a lot of time in. Unless they trust you enough to take your word for such things, at least provisionally. On the good side, they may convince you that you are wrong, which beats cold, hard reality convincing you down the road.

For things like a design being more testable, if they don't agree that it is more testable then it's pretty much the same as the first example. If they don't agree that it's desirable to be more testable, then you have to bring it back to things they understand. This would most likely be management, and you can talk about lower development costs in the long term, less QA, more predictable processes (since the length of repeated QA cycles is hard to predict), etc.

I think part of the problem is that you underestimate how difficult it is to get a team to agree with you on anything controversial, even if you happen to be correct (and of course you may not be). Programming is partly a sociological exercise and you may need to schedule time to actually go down some of those rabbit holes, since a great design that no one understands or gets behind is rarely a great design in practice. So don't think of that time as wasted, think of it as a necessary part of your project's success. Even though it would be so much easier if you could somehow skip it.

Answer 4

Being the sole voice of change is never an easy thing. The first challenge is usually to get other people on board with you (Hopefully there are some in your company who are more open minded than the rest). If you can grab the attention of a couple other senior developers/managers to join your crusade, those combined voices will be ever harder for the rest to ignore.

I find a good way to explain to people is through providing concrete examples of past mistakes made in projects which they have been actively involved in (e.g. "Have you ever tried to debug this thing? It's been like this for years and noone knows how to fix it.."). Better still, applying those 'new' design ideas and principles to a small/trial project and being able to show off how successful it's been at the end.

Depending on the attitudes of others in your company, change may come quickly, or it may be like trying to swim through treacle. Some managers are completely immovable unless they have solid statistics/proof in front of them, where others are quite keen to be keeping up with the latest thinking.

You might need to try different tactics depending on who you're dealing with; Suggesting that money/time/effort might be saved and quality might be improved is a good way to grab the attention of non-technical managers; and the promise of easy automated testing appeals to quite a lot of developers who usually can't stand spending days running through the same test spreadsheets repeatedly.

Answer 5

Depends on the audience! As developers we developed an intuition for good and bad code, and use vague emotional terms like "code smell", "ugly code", "beautiful solution". This only works when communicating with other developers with the same mindset. Try to explain your non-technical CEO that you should invest x man-hours into making some code "more beautiful" you will most likely fail spectacularly.

You need to be able to make the case that any given design improvement will either

• save money for the company
• make money for the company

For example, what is the case for adhering to the single-responsibility principle? If each class have a single responsibility it makes it much easier to locate and fix bugs, and it makes it easier to add features and improvements. Less time fixing bugs and adding features = money saved.