Principles of simplicity

As I’ve wrote before, simplicity is very subjective and is not considered a first class design principle as unit testing, design patterns, UML etc. However, it is in my opinion possible to use guidelines of simplicity in an objective manor and make simplicity a part of the coding standard in any company. As with many other design principles, it can only be reinforced using code reviews and that is exactly how we enforce it at Traceworks.

Here is a list of some of the principles of simplicity that we use. Some of them are borrowed from other principles or philosophies, but together they form a nice simplicity guideline I think.

1. Simplicity or not at all

Some developers tend to over-complicate a task and ends up writing too many classes to solve a simple problem. The ability to take a step back and observe the problem space before digging in to a detail is hard, but it will keep you from over-complicating matters. The more experience a developer have, the easier it becomes to find out how many steps backwards to take in order to fully understand the problem space.

I’ve always believed that if you cannot find a simple solution then don’t do it at all. That’s because if you cannot take a step back and get a good feeling for the problem, then you don’t understand it enough to see a simple solution – and trust me, there is always a simple solution. If you don’t understand the problem you are trying to solve, then you probably cannot solve it. More

2. Don’t build submarines

It’s a common fact that IT projects take longer than scheduled even if you schedule for delays. Books have been written on this fact, but it also has an impact on the simplicity of the code written.

If you design a huge project with many components, tiers, whistles and bells then you most likely will be delayed. In the eleventh hour up to a deadline, you will probable not have time for proper testing and code reviews. The problem is that you might never get back to that code before it breaks 6 months later. Maybe it’s your co-worker who will fix the problem, but end up looking frustrated at a complex submarine not knowing where to begin.

If possible, make sure that you design the project in modules that can be added after the release of the core product. This can be done in web projects easily, but prove very difficult for desktop applications.

3. Test when appropriate

Testing is one very important factor of the development cycle and there are many different tests to perform. Unit testing, use case testing, performance testing etc. Tests are good, but if you test everything to the smallest detail every time, then you probably waste a lot of time on it. Test where it makes sense and use different combinations of the various tests for different libraries. Not all code needs unit testing and not all code needs performance testing, but they need some tests. Be smart and don’t spend more time writing test cases than you do on writing or designing your application unless it’s your job. Read more at Testing your code.

4. Be precise when naming methods

A method must have a name that tells exactly what it does. Luckily, a method should at all time only do one thing to be simple, so this is easy. A method called Send could be a bad name if it actually creates a mail object and fill out the sender, body and subject and then passes it on to another method that actually executes it. A more precise name would be CreateMailMessage.

When the method names become precise it also becomes very simple to understand exactly what is going on where.

5. Comment your code the simple way

Code commenting can be done in a myriad of ways, but there really is only one that keeps your code simple at the same time.

Don’t comment the individual code lines in a method or property, but keep the comments above the class, method, property or interface. The comment should answer the questions what, why and how. This can be done quite easy when you have giving the method a precise name and you can spend more time explaining the why than the what because the name tells what it does.

This wouldn’t be a rule if there aren’t any exceptions, so of course there is - one to be precise. If your code contains a strange quirk to work, then you should write a note above that piece explaining why it is done that way.

Clear comments also tell others what your code does and are therefore a good method to make your code simpler to understand.

6. Steal borrow and simplify

We all use code pieces found on the Internet all the time. Search Driven Development is the new developer philosophy, but be careful about the code found on the web. It might work, do the job and get you over the finish line, but it might not be the easiest code to understand. If you don’t understand it when you paste it into your code file, then you probably don’t understand why it breaks 6 months later and then what do you do?

Make sure to clean up the code you find on the web and simplify it as much as possible. Don’t wait to do it, because then you probably forgot exactly what it does and how. Do it right away.

7. It’s not a question of fewer code lines

I get this a lot. Apparently it is a common misunderstanding that simplicity is a question of writing fewer lines of code. That is not the case. Simplicity is about removing everything that can complicate the process of writing and maintaining software.

8. Don’t be a rock star

Know your limitations and don’t be afraid to ask for help to solve a problem. If you continue in the wrong direction because your rock star mentality doesn’t allow you to ask for help, the code you write will end in a mess. If you can’t get your head around the problem, then you should ask for help. Otherwise you are clearly not the right person to solve it.

By asking others for help, you might just learn something.

9. Learn much about much

To be able to find the simple solution to any problem, you need diversity. The ability to see a problem from multiple angles is a powerful tool in problem solving but it requires that you have a lot of angles to use.

Read books, play with new tools, languages and technologies. The more you know about different approaches to a certain problem, chances are you find the right solution a lot earlier.

10. Don’t trust your simplicity instinct

This might be the single most important rule of simplicity. The only person who can tell if your code is simple is anyone but yourself. A code review is the best way of finding out and at Traceworks, it is always the reviewer who decides whether or not the code is simple enough and if the comments are sufficient.

Over time we have all learned what gets you through a code review and therefore have begun to write simple the first time. Learning by doing.

Conclusion

Simplicity is an implementation philosophy and it’s a very important one. The list of 10 points are guidelines and there are many more, but then you’d probably fall a sleep reading them all. Congrats for coming all the way down to the conclusion btw. If you have read it all, then you probably find it interesting either because you agree or disagree. Either way, simplicity is the most important factor in my work and it has prevented many headaches in the past.