Writing simple code is complicated — here’s how to do it
I have a confession to make. When I first began my career, I was under the impression that the more complicated and longer code was, the more skilled the developer had to be. How can a dozen lines of code compete with hundreds that do the same thing? The latter was clearly doing more, meaning it had to be better.
A few years into my career I met a fellow programmer who was undoubtedly brilliant at coding. He had memorized an entire framework’s documentation, he was utilizing techniques that were considerably more advanced than what we were doing on our platform, and he never failed to showcase his love for regular expressions by applying them everywhere. He was hired and given a simple project to do — update an existing piece of code by adding a tiny new feature to it. This was two days' worth of work at most. Roughly three weeks later, he finally delivered his code which resembled more of a patent application compared to the simplistic version it replaced. The result was code that was so overly complex that it was buggy, more difficult to maintain, harder to update, slower in performance, and ultimately was purged.
It was then that a shift in my beliefs began and I started to consider that perhaps, simpler code might be the better approach. We had already experienced a similar shift in hardware at the time with the introduction of the iPod and iPhone which replaced their predecessors: the multi-button mp3 players, and phones that everyone was accustomed to. Applying this notion of simplicity to software seemed like a terrible idea at first, especially since at the time, most code that was found online and in books was overly complex.
For the next decade, I focused on writing clean, simple code that just about anyone could read and understand. Suddenly, coding began to spark joy again. I was clearly not alone in my endeavor. I began to meet a lot of like-minded developers who have written brilliant code that’s pleasant to read and to understand without comprising functionality. My favorite example of this is in the PHP community where the framework Laravel leveraged some of the amazing work by the folks over at Symfony and created a beautiful new framework that’s as elegant as it is powerful. Gone are the machine-friendly method names, replaced with a more human-like language.
Here are a few techniques that you can use right away to help you avoid writing complicated code and make maintenance a joy.
Break down the problem
It’s actually a lot more difficult to write simple code than its complicated equivalent. It’s easy to get stuck on a problem, hack and patch it until it works, and then move on to the next issue. However, taking the extra time to simplify it isn’t always obvious. How exactly do you take a problem that’s fundamentally complicated and simplify it? The first step is to break down the problem into manageable pieces.
There’s a popular programming principle known as the Single Responsibility Principle (SRP). The idea is that a method or class should only be in charge of exactly one thing. A method should not, for example, retrieve a fruit, wash it, peel it, cut it, plate it, and eat it. Instead, there should be a main method that calls each one of these actions separately. These methods should have easy to understand names — e.g get, wash, peel, cut, plate, eat. When someone sees fruit->wash() it’s pretty easy to understand what’s happening without diving deeper into the code.
Now that you know about the SRP rule, I’ll tell you a little secret, it’s okay to break the rule. It’s totally acceptable to have methods that occasionally do a tad bit more — sometimes it’s just the cleaner and better approach. As long as you don’t abuse it, the coding gods will not punish you.
Start off clean, and stay clean
It’s easy to get tempted to code in a sloppy way just to “get it to work” and then attempt to clean it up later. In my experience, that’s more time-consuming. It’s surprisingly a lot easier and faster to start off clean and keeping it that way. In the fruit scenario above my approach would be to create a main handler method, say consume, and figure out all the steps that “consume” would need to take in order for a fruit to be eaten. I would then write each step in plain English as comments (to keep track of what I need to do) and one by one, I would cross them off by coding the corresponding method.
This is, by the way, a good opportunity to do some Test Driven Development (TDD). Since each of the methods will do exactly one thing and we have defined exactly what that one thing is, we can code each method and write tests for them as we go. Suddenly, our code has started off clean and has been fully tested. There is no need to go back, refactor our code and in the process, break things again.
Naming things is difficult but crucial
Naming things is tough. In the above example, I mentioned that it’s wise to start off clean. That also includes naming your variables, your classes, and your methods properly. Avoid abbreviated names. Be verbose and explicit instead by writing complete variable names, your editor will autocomplete them anyway and it makes your code easier to understand. I know it’s tempting to have a variable named “i” for an iterator but what ends up happening is that if you have a loop inside a loop, you end up with variables named “i”, “j”, “n” and so on, and suddenly, your code is harder to read.
My other rule of thumb is to not exceed three words for a method name. Why? Because if you need more than three words than your method is probably doing too much. Of course, there can be exceptions, but that’s exactly what they should be, exceptions.
My last tip is to aim for consistency. Let’s say throughout your application you have methods that create, update, and delete records, try and use the same naming convention across the board. If you use different words to represent the same action, for example, “create”, “add”, “insert” for adding a new record, then it becomes difficult to remember which is which and you lose your train of thought as you code by having to look them up. Before you settle on a name, check your framework and see if it already follows a naming convention and adhere to those standards if possible.
RTFM — Read The … Fantastic Manual
Here’s a spoiler, most of the code that you will write in your career has already been written before. Programming languages and frameworks come with a sleuth of helpers to make your life easier. The next time you need to manipulate a string or an array, for example, take a look at the documentation, chances are that there’s a piece of code that will get you pretty close to your end goal. Not only do you not have to write the code yourself, but the helper has been tested and handles edge cases that you might not think about. This removes clutter from your code and keeps things tidy.
Here’s a pro-tip, If you’re reading the documentation but you’re still not entirely sure how to use the helper, take a look at the test suite. The test suite should show you all the ways you can use a particular method. If needed, dive into the source code and find out for yourself.
Furthermore, many languages and frameworks allow you to include packages that other people have written. Feel free to use other people’s packages instead of writing your own, especially if the package is well maintained, documented, and tested. This will not only speed up your development time, but it will keep your code clean and you now have a few components less to worry about.
Coding Standards
Another way to keep things clean is to adopt a coding standard. There is no need to reinvent the wheel and write your own. Look at what the framework (or community) is using and follow that standard. By having your statements and braces perfectly aligned, by following the same convention from one file to the next, and by having everything properly named, you remove unnecessary friction when doing a quick glance.
Fact: Clean code leads to simpler code. If you hate having to be strict about following a coding standard, then download a tool that will do it for you, typically these format your code for you on save. You should install a formatter even if you’re already following the standards, just in case.
Understand the Why of a solution
Sometimes, you’ll get stuck on a problem, do a quick search on StackOverflow, copy/paste the solution and your code suddenly works so you move on. This is a terrible practice. Instead, spend a few extra minutes to figure out why this solution works. Luckily, most answers on StackOverflow already explain the reasoning, so take the time to read it. It’s one thing to get your code to work, but you’ll be in a different coding level if you know why and how the code works. When it will be time to refactor or revise that code, you’ll thank me.
Create a flowchart
No, I don’t want you to go and Google the best flowcharting app. Grab a pen and paper because that’s all you need. Don’t go flowcharting everything, that’s a waste of time (unless it’s a requirement, then by all means). Instead, for overly complex problems create a flowchart by breaking down the problem into small bite-sized and mapping out all the possible paths. Sometimes, spending a little time brainstorming will save you more time and headaches in the long run. It will help prevent any unwanted “gotchas”. If you’re not sure what a flowchart is or how to write one, you can read my article about them.
Take a walk
My last tip is to take a walk, no this isn’t a technical term, I mean take a real, physical walk. If you’re in the “zone” trying to debug an issue or coding a particularly difficult problem for longer than expected, then it’s time to get up and take a distraction-free walk alone. There are so many benefits to this that I could write an entire book about it. In brief, by getting up and walking, you will get your blood flowing which will make you less lethargic. As you walk, you’ll start to ponder and even though you’re not at your desk looking at code, your brain will continue to work in a fresh state and you might come up with the solution. This break from the screen will do wonders, I promise.
That’s all for now. If you have any other tips, please post them in the comments, I’d love to hear what you think. If you’re a fan of clean and simple code, or want to read more articles like this, a clap would be appreciated.
You can also find me on Twitter as @tkaravou
