What Are the Fundamentals of Good Software Design?

Don’t fall into junior developer pitfalls or overcomplicate things

In this article, I want to elaborate on the broad concepts of good software design rather than the specifics that may differ a little from language to language.

When is code good and when is it bad? It’s a subjective and controversial topic. There are a lot of language- or framework-specific rules and guidelines, but I have a strong belief that good code or good design is not only or always tied to them. Often, they make code complex, scattered, and over-structured. Therefore, I believe that good design is subject to its use case.

Luckily, I think there are still some ways to determine if the software can be considered “good” or “bad” for its use case.

Good Design Is Simple

Often, I come across code that is perfectly structured with all the bells and whistles, set up with proper interfaces, and it adopts specific code patterns and code style tools that do not return a single error or warning. But still, I think it sucks.

Every time something is written, it should be proportional. A lot of developers adopt patterns just for the sake of patterns. They’re almost yelling, “Look how good I am at adopting this pattern I just read about” instead of really understanding why they chose a specific pattern.

Good design is often simple. By that, I mean proportional to the size of the solution they provide. If you provide a simple feature to the application that is only used once, should you be using all kinds of fancy stuff? Think about if your code complexity is proportional to the solution you are providing. Is your feature going to be the backbone of your application or the base of an extension or inheritance in your application? You better have it well structured. Is it just a solution to a small problem in your application? It better be as simple as it can be.

We Tend to Overcomplicate Our Features

When talking to the Project Owner of our application, we retrieve requirements. After first drawing out our ideas for the implementation, we often overcomplicate the initial design of our approach. It’s often beneficial to sit down with a few developers and really drill down what is actually needed. There are a few ways you can make sure you provide the easier solution possible.

Aks the right questions

As developers, we are often asked to do something, and we just do it. This on-demand behavior is probably normal for junior developers, but as you progress, try to ask intelligent questions and be sure those questions are answered before estimating or designing the solution. When you ask certain questions over and over again, you also train your Product Owner or management to think about these questions before requesting a feature. Questions like:

• What is the end-goal of this feature?
• Who is going to use it?
• Is there a simpler way of achieving the same goals?
• Will it make the application bigger and more complex? Is that worth it?

Divide the solution into multiple parts

The first thing I always do is step away from the application the feature needs to be implemented in. Then think of the smallest piece of code you can make and deliver that brings you a bit closer to the goals set for this feature. Do this for all of them, reassess if all of the steps are necessary, and estimate their development time separately. Also, try to develop those elements in as standalone a fashion as possible. The easier it is to swap out functionality, change it, or delete it, the easier it is to code.

Challange your Product Owner if certain small features are really essential

As you divide your approach into small parts, it is often easier to discuss it with non-tech people. This opens up the possibility to discuss it with the team and Product Owner and reassess if all parts are needed. Since you estimated them already, a better value-based decision can be made on if the feature is worth it.

Don’t forget to estimate the level of complexity it adds and how it affects the cost of maintaining the application.

Good Code Is Easy to Change

When code is easy to change, it’s cheaper to maintain, easier to understand, expand, delete, and again, change! As written in the book The Pragmatic Programmer: “A thing is well designed if it adapts to the people who use it.” In essence, all design principles are a way of making code easier to change. Decoupling, single responsibility principle, DRY. These are all principles that make your code better and easier to change.

Why I Hate Comments in Code

When you need to comment your code, it basically sucks. When you need to explain why you are doing something, the code is not self-explanatory and should probably be refactored anyway. Code comments are a clear sign of bad code, and there are a lot of simple steps you can take to make your code more readable.

Comments do not make up for messy code. We tend to write extra comments when code is confusing or makes dangerous assumptions.

The only comments that make sense are:

• Legal comments
• Explanation of intent
• To improve readability
• Warning of consequences
• To-do comments

How to Write Better Code

There are a lot of simple principles that can help you write easier code that your colleagues will like and love to work with. For each of these, a completely separate article can be written, so here is a simple list to start your journey toward better code.

Classes

Classes should be small. How small? As small as they can be. A class should only have one responsibility and its name should be derived from that. If you cannot think of a logical and descriptive class name, it is probably too big.

Methods/functions

Like classes, they should be small, do just one thing, and have an explanatory and simple name. Be careful with idents. A lot of indentations is often a sign of a messy method. With Foreach and switch statements, be sure to write the actual executed code in a separate function that makes it more like an index of what the method actually does for the different implementations.

Meaningful names

Classes, functions, and variables should all have meaningful names. Never use $a = b;, for example. Let your code be the documentation of your functionality and intent.

Formatting and code style

Be sure your entire application and your complete team use the exact same code style — and be very strict about it. Every IDE and language has tools for this. A consistent space or newline can make all the difference. When it's not consistent, it can drive you insane. Being really strict in this area will instantly improve the cleanliness of your application, especially in languages that are not very strict in this regard.

Want to keep in touch, questions, or comments? Join the conversation on Twitter