Before I learned how to build apps with code, I thought software development would be like building something out of wood… you learn a couple of basic skills, put a shelf together, and then the project is done forever. I honestly thought the hardest part would be learning fancy techniques or complicated algorithms. Boy was I wrong.

What I didn't understand is that software is never actually done… and that the never done-ness is actually the trickiest part of software. Sure, you can hack an app together quickly, but it won't run in a few weeks after the dependencies update. Sure, you can write a whole bunch of code and deploy it, but will you be able to change that code easily?

In many ways, what makes software engineering difficult is actually how easy it is to write code, install some dependencies, and get something running; This leads to implementing short-term solutions and bad practices that bite back hard later on.

As my apps started to get out of date and out of control, I quickly found out that software engineering is not just the creation of software, it's also the improvement and maintenance of it. As it turns out, improving and maintaining code is extremely hard because of compounding complexity as the codebase grows, and technical debt that accrues overtime. So, how can we start actually engineering software, rather than just continuing to commit more and more code until we end up with a tangled mess?

Learn from my mistakes

To avoid disaster, you need to dedicate time to the quality of your codebase. To help get you started, I'll give some examples of ways to improve your code as you are writing it. Some of these are written in pseudo code (vaguely ruby-ish so I refer to methods instead of functions) but many languages have similar concepts so the underlying principles will translate:

1. Extract a method to reuse

DRY (Do not repeat yourself) is a well-known principle of software engineering. If you create methods that encapsulate a certain behavior, then you can reuse the method and will not have to change the code in multiple places if you need to update it later on. This technique also cuts way back on the amount of code in your codebase, making it easier to keep a handle on. If you find yourself writing the same code again, pull it out into a reusable method.

2. Change comments into descriptive code

It's so easy to update some code and forget to update the associated comment. This leaves outdated comments in our codebase that can confuse or lie to us later. Instead of writing comments that detail what a method does, make a small method and write the comment as the method name. For example… instead of writing:

# This creates or updates a subscription

I could name the method create_or_update_subscription.

3. KISS (Keep it simple…)

Sometimes when we are trying to get something working we write really long lines of code like:

if user.confirmed && user.subscribed && user.profile.complete || user.team.no_profiles_allowed?

A lot going on here! Now I have to keep track of all of these conditionals, and if I ever change this code I will have to review what each on is checking to make sure I don't mess up the implementation. Instead I could pull some of these out to smaller, more descriptive methods… perhaps pull the first part into a method called user_onboarding_complete? Then the code would read:

if user_onboarding_complete?

This is much less confusing. Now if I need to know more about the implementation details of these methods I can go look at them, but I can instantly see the higher level purpose of the code quickly.

Want more ideas for how to keep a codebase that is easily improvable and maintainable over time?

These 3 small improvements techniques will yield huge gains as your app gets larger and your code multiplies, but if you want more ideas, you can join the free 30-Day code quality challenge to get one daily maintenance or improvement challenge for you to tackle a day. It is programming language agnostic and open to anyone.
I signed up for a previous cohort and found it very useful. (Full disclosure I am running the next cohort that starts May 3rd)

Photo by Oskar Yildiz on Unsplash