Recently, I revisted the classic Clean Code by Robert C. Martin to recalibrate my coding habits. After re-reading the core principles, I can see why it sparks so many debates on Reddit. It’s unapologetically opinionated, presenting itself as a collection of hard rules, even if that wasn’t the author’s intent.
Let’s look at a couple samples:
Functions should do one thing.
It doesn’t take long to stumble upon other pieces of advice that feel a bit rigid. Right along side the “one thing” rule, here’s another:
Avoid negative conditionals
In the former, Martin argues that functions should be broken down until they only do one thing, which sounds good in practice but can lead to a fragmented code base if followed literally.
In the second example, Martin argues that negative conditionals are slightly harder to understand than positive ones, offering the following snippet:
Yeah, that’s confusing, and I can see how it applies in this scenario. However, it’s still an oddly subjective thing to pick at. I can use the same variable names and rearrange it like this:
Is it still preferable? I don’t know; I might have a different answer depending on if you ask me in the morning or afternoon. The clarity of these examples, and many others, all rely on context.
Collectively, they can be the essence of a “clean” code base, but “clean code” may mean different things for different people. If I’m working on a solo project, my code is “clean” if I look at it and understand what’s going on after not touching it for 6 months. In a team, clean code may mean following established conventions that allow new developers to quickly get up to speed.
The definition for clean code is not clear-cut, and maybe books like Clean Code exist to address this ambiguity. Although ever-shifting, clear boundaries do exist. Let’s look at some principles that I think are applicable to almost every scenario.
Commented-Out Code
Martin says it best, “Commented-out code is an abomination.” Every time I’ve commented out code, it was because I was either debugging something or using it as a reference while writing something new (skill issues). I usually clean up after myself when I’m done, but finding it weeks later still there? That’s just shameful.
Inconsistency
Are your variable names too short? No problem, as long as they’re all too short ¯_(ツ)_/¯. Consistency creates patterns, and patterns make navigating and/or learning a codebase easier, in my opinion.
Follow Standard Conventions
Right alongside consistency, I’m a big fan of sticking to conventions, if there are any to follow. I like linting tools for this reason. Like a good friend, they warn you when you’re breaking stylistic rules, and they enforce standards that we wouldn’t normally think about. I always try to use linting on any serious project.
Names Should Describe Side Effects
This one barely made the cut. Martin generally advises against side effects (a function that changes something outside itself), but then he also gives us this rule. In reality, side effects are often unavoidable in any non-trivial system. Naming them appropriately is something we should strive for.
A simple example of when I applied this rule comes to mind: While working on my NES emulator, I decided to make the CPU Read function consume a cycle, mimicking the real hardware behavior. To make this clear, I renamed the function to ReadAndTick instead of just Read. The original Read still exists without side-effects, used during debugging, where I may not want a side effect from reading a value.
Is this rule applicable in every case? No, because sometimes the entire purpose of a function is to cause a bunch of side effects, like React’s UseEffect, and as far as I know, we cannot rename it. Still, when possible, I think it’s worth the effort to attempt to describe what your function does. If your function has too many side effects, then breaking it into smaller pieces—another Clean Code guideline—is worth the consideration.
Conclusion
Books like Clean Code provide guidelines. I could’ve just said that upfront and skipped writing the whole article, but here we are. While the book does contain a lot of hot takes, it’s important to remember that Robert C. Martin isn’t just some guy with a blog on the internet. Each principle he outlines stems from specific scenarios he’s encountered through years of development experience. There’s no doubt each principle is relevant given the right circumstances, just not in a general, blanketed sort of way.
That’s my take! Thanks for reading!