Choosing the Boring Solution

When solving a complex problem, it’s sometimes very tempting to choose an excellent solution. Not only will this solve the problem – but it will also impress your teammates and bring you everlasting glory.

An even better solution, however, would probably be a boring one. One that is easy to understand, even for your junior colleagues. One that is well-known for your platform and language. One that is entirely not extraordinary.

Using such a tedious solution means that you’re using simple vocabulary, which significantly increases the chances of everybody understanding you. This will make it a lot easier for everybody to follow along – including new team members (and yourself, a couple of weeks after you’ve written that code).

Aiming for Simplicity

Acronyms FTW! Car enthusiasts might now think of BMW, but software developers should think of KISS and YAGNI.

“Keep it simple, stupid” should remind us that the simple solution will always beat the overengineered solution. The reasons why this is true are almost endless. And they might be easier to understand when looking at the opposite: complex code.

  • Complex code is a perfect hiding place for mistakes.
  • Complex code is hard to understand, for your coworkers and yourself.
  • Complex code cannot easily be extended.
  • Complex code cannot be reused. And, last but certainly not least, writing complex code will cause your teammates to brand you as an outlaw.When a more straightforward solution seems sufficient right now, you should always aim for it.

“Writing complex code will cause your teammates to brand you as an outlaw.”

When you realise that your solution isn’t essential at all, you should drop it. This is what YAGNI is about – “You ain’t gonna need it” reminds us to stay modest when planning the volume and scope of our implementations. Will users need this feature? Will they need this option within a feature? These questions, of course, will translate to our code: will we need that class/ module/routine?

Stack-Overflow-Driven Development

Thank God for StackOverflow.com. I seriously can’t imagine my (programming) life without it. And with it being one of the most visited sites on the web, I guess I’m not alone.

There’s a long friendship between Stack Overflow and me. It helped me countless times when I was stuck on a problem. It gave me an idea of how other people had approached the same problem. Sometimes these other people helped me solve my problem. Sometimes they gave me a hint for a possible solution. And sometimes reading their issues at least let me know that I wasn’t alone with a miserable bug…

After hours or even days of searching and trying different things, your shields are down. You are crawling through your code on all fours like a man who’s lost in the desert. But all of a sudden your search is fruitful! Eureka! Searching Stack Overflow has finally yielded a piece of code that works!

That’s when you have to watch out and resist the temptation to take code that works for the system that’s good. What you’ve found on Stack Overflow is – in all but the rarest cases – not a solution but rather a clue. It can certainly make for a great pointer, but it was not written with your exact problem/ requirements/ constraints/codebase/application in mind. And sometimes, it might just be a dirty hack.

Embrace Stack Overflow as a good source of guidance for specific problems. But also take the time to thoroughly and honestly evaluate if you’ve found a real, reliable solution.

Design Patterns

Sometimes, a solution is so beautiful, and you wish you had the right problem to apply it to. But unfortunately, issues come first. As impressive as your new screwdriver may be (imagine a handle made of gold, with your initials engraved, of course, if the problem at hand is to knock in a nail, it makes for only a less than perfect solution.

Now, after teaching you all I know about manual craft, let’s return to software development – and consider “design patterns” as your toolbox. Every design pattern you know (and understand) is an instrument in your toolbox. It’s certainly great to have many of them!

The problems start, however, as soon as you let the patterns dictate your coding. They should be there to support you, to propose a proven solution – for the right problem! Programming paradigms should be used where they fit and not be enforced. Your components should be designed with your application’s requirements in mind – not with a beautiful design pattern.

In cases where you’ve indeed found a helpful pattern for your current problem, there’s only one more thing: be sure to understand the pattern and its consequences on your coding.

Creating Good APIs

I’m sure you’ve used a third-party API at some point in your dev career – for example, to create new contacts in your CRM, to send emails through a newsletter service, or to do anything else with a third-party service virtually.

If you’ve interacted with a couple of such APIs, you will undoubtedly have noticed some differences between them: using one was probably more pleasant than the other. It’s easy to see which API was designed thoroughly, by an experienced developer, and perhaps with a lot of effort and thought. And it’s just as easy to be frustrated with an API that was designed poorly and sloppily. The former was probably a joy to use, while the latter was perhaps… not.

Since the effects are so visible, most developers tend to quickly agree that it’s almost a duty to design public APIs in a careful and thought-out way. Nobody wants to work with a crappy API – and nobody wants to burden other developers with using their API being crappy.

Modern software design puts great emphasis on the concept of “application programming interfaces”. However, as most developers already know, the idea goes a lot deeper and is not exclusive to a public interface. Instead, you should build APIs inside your application, for internal use, too.

Approaching these internal APIs in the same way you’d create a public one can make a huge difference: your colleagues (and you) will want to interact with this part of your application. Making the interaction as easy as possible for these people is one of the best goals you can have.

A secure, thoughtful API is probably the part of your software where quality matters the most. Your colleagues might forgive you a little sloppiness in the internals of this or that method. But they won’t (and shouldn’t) forgive you for creating a dangerous API.