Clean code reads like a beautiful story
Clean code feels like poetry in motion, gracefully and elegant. It reads like a beautiful story, clear and concise story. It sounds like RNB lyrics; simple relatable stories, a great bridge and repeat. Clean code is an art as much as a science.
Before we get going lets set the scene. A long time ago the pop culture image of a developer was one of someone working in the basement churning out code that no one else understood. Perhaps it was true at some point, but that is not the case anymore. We rarely work in total isolation, we often work in teams with others sharing code and collaborating.
Whenever you write code it’s worth remembering that it’s not just for yourself, other developers might have to read and refactor it someday. Think about them, will they understand what you’ve written or will they have to consult you to understand it. Gosh, that’s embarrassing, I know because it happened to me. Meditate on this when you write your next piece of code and this will steer you towards avoiding unnecessary complication.
Guidelines to writing clean code
Use self-descriptive variables and function names
Context adds understanding to any scenarios, conveys more information and make events more memorable. In this context, code, I advocate for putting more thought into how we name variables. A singular variable name for example $time, raises more questions than it answers! I think what time: credit card expiry time, time since I read this, years since I was born, time since I listened to Solange’s album, time since millie rocked, time since Kanye tweeted… Try using something more descriptive like $creditCardExpiryTime, $timeSinceLastRead, $age, $timeSinceKanyeTweeted (don’t judge me) . It’s better to let your variables describe what you intend to say such that it requires no additional help with no further explanation. Trust me, this will save time down the line.
Don’t repeat yourself (dry)
I’m sure this topic has been covered to death, so guess what? I’m going to cover it again, because it’s really important. You’re a developer because you’re curious about how things work, you’re constantly optimizing because on some you want to make things better and maximize your time and save earth for the forces of evil. Ok, that last bit isn’t strictly true but you get the idea.
The idea is to avoid repeating the same information all over your code by using a function to abstract the logic out. DRY saves time and effort; it makes your code more maintainable since you only have to make changes in fewer places in your code.
Single-use function
Imagine that you had a car and the start button on one push starts the car, but also doubled as the hand brake when you pushed it twice in quick succession. You see the problem, right? I admit that’s a bit of an exaggeration, but the principle still stands. You could probably manage to drive the car, but any changes to the start button might ruin the breaks and vice versa. Should those functions be separate buttons?
As much as it let your functions serve one purpose, perform one task and be done with it. This has its benefits:
- Its easier to debug and test as you likely have on one idea to debug at a time.
- Replacing that function is easier without any repercussion.
NOTE: Single-use function != smaller functions, it just means a function serves one idea.
Avoid using magical number
If you find yourself asking what, why, huh about the purpose of a number while reading a code…it might as well be magic. This is often the result of hard-coded literal values that appear in your code, for example,
$total = 1.08 * $price;These numbers often leave anyone other the author else confused as to what it means. To resolve this assign 1.08 to the constant RATE.
const RATE = 1.08;
$total = RATE * price;*If you change the value, you only need to change it once in the constant declaration.
Conclusion
If I could boil it all these guidelines into one phrase I’d say – take pride in your code, how its read, perceive understood. Clean code is self-documenting, it tells us what its about on its own. Strive for that!
To riff on a previous saying by the legendary Johan Cruyff.
Football like Coding Can Be Simple but It’s Difficult to Keep It Simple!
— Tobi Ogunleye
