Optimize Your Code for Clarity

The single biggest improvement you can make to any piece of code is to make it simpler to understand.

Every other improvement depends on the original code’s purpose being correctly understood in the first place.

More often than not, this means writing more lines of code, using more spaces, longer variable names and creating more files. These concepts aren’t typically seen as optimizations.

Optimize invokes the ideas of smaller codebases and faster performance, but I’d like to look at it from a different perspective.

Code can be optimized to have faster comprehension speed and smaller mental footprint.

Faster Comprehension Speed

Since you can’t improve what you don’t understand, the faster your code is understood, the faster it can be improved.

The purpose of this code isn’t clearly stated. You can improve the comprehension speed of this code trivially with a single-line comment.

Instead of reading 10+ lines of code and guessing, you can read one line and immediately understand what its purpose is.

You understood faster and you can get to work faster. Code successfully optimized!

Smaller Mental Footprint

Something subtle happened in the previous example. $t changed from a string to an array. Every piece of code after that point needs to be aware that transformation took place, else they’d expect a completely different data type and errors will abound just because of that change.

Mental footprint is how much of the code you need to keep in your head to effectively work on it.

To accomplish this, you can break the code up into smaller chunks or you can ensure you keep as little state as possible and avoid changing it as much as possible.

In the case of our freezing point checker, I’ll turn it into a function that doesn’t affect the state of any variables outside its scope.

With a function name like that, you don’t even need the comment. What does your code look like inline?

When optimizing the bit of code that actually does the checking, you don’t need to be aware of the previous state of $t. You expect a string and throw an exception if you’re not given one. Additionally you don’t mutate any outer variables, which means the lines of code after your temperature check don’t need to be aware of anything you’re doing during the check.

Make it easier for yourself and others to quickly understand what was done and how to improve it without fear of breaking things.

Hide implementation details in appropriately-named files and functions. Don’t mutate state outside your file or function.

Optimize your code for clarity.

Get New Posts via Email

I don't always post, but when I do, you can get it sent directly to your inbox.

Join 15 other subscribers