Clean Code Isn’t Enough; It Must Be Crystal Clear, Too

Think of a sparkling clean kitchen. The counters shine, the floors gleam. Every fork and plate is in its place, the pans have been scrubbed clean and there’s not a crumb in the trash can. A fantasy. In the real world, kitchens get dirty quickly. Code too can get messy, especially in incompetent hands.

Many top-talented programmers emphasize clean code. And a quick way to separate talented, dedicated programmers from people cashing paychecks is to look at how clean their code is (or isn’t). Yet what’s just as important is clear code. 

Imagine yourself in that sparkling kitchen. It’s what dreams are made of. The fridge is stocked with fresh, tasty ingredients. You’ve got a specific recipe to make so you pull out the cookbook. There’s just one problem, it’s written in Chinese and you can’t read it! 

As beautiful and well-stocked as the kitchen is, you’ll struggle to cook up a good dish if you can’t follow the recipe. In a best-case scenario, you might be able to use Google Translate to figure things out. The chance of misunderstanding or interpreting something, however, will be very high.

When it comes to coding, clarity is every bit as important.

Clean code provides a solid foundation but it’s not enough for exceptional code. Removing coding antipatterns and the like is great but at the end of the day, if you can’t understand the sparkling clean code, it’s still difficult to work with. Maybe you can suss out the meaning of the code, but there’s a risk you’ll misinterpret something.

Clean code is somewhat uncommon. A lot of lesser programmers simply throw code together and only care if it functions. Clean code that is clear and easy to understand is even more rare. Even talented programmers don’t spend a lot of time considering how clear their code is or isn’t.

A talented programmer may not even feel there’s a need to write clear code. After all, the writer often understands the code. But when someone else comes along, say a talented junior programmer, they might have to spend hours simply trying to figure out the meaning of the code.

A truly exceptional programmer will consider whether or not other programmers can understand their code. He or she will strive to write beautiful, clear code that others will be able to work with easily.

So how do you write clear code? Consider other perspectives while writing the code. Could you pass this code off to a third party and would they be able to easily understand it?

And then, more importantly, test to see if you succeed. Give the code to someone and ask them to review it and see if it’s clear. And remember "clear", not clean. Your classes may be beautiful, and your code constructs might be stunning. But that’s "clean" code. What’s more important is whether other people can work with the code.

So ask someone to debug a problem in the code within 30 minutes. If they can’t, your code might be difficult to understand. If your fellow programmer has to ask question after question, that suggests they’re not finding the answers on their own, which may be because your code is hard to understand.

Clean code often impresses on first impression. Clear code puts programmers over the moon once they work with it. Ultimately, clear code is easy to understand, modify, and maintain. If you were taking over programming for software, wouldn’t you want the code to be all of the above? Of course!

You can take things a step further, by the way, and make your code truly open. Don’t ask for people to simply report bugs. Ask them to check for clarity. As they provide feedback, you’ll learn more about how other people see and interpret your code. That way, you can write increasingly clear code.

In a restaurant, dirty dishes and cockroaches are sure to send customers packing. And who wants a glass of dirty water? No one, we want it crystal clear. When cooking up great code, you can start with clean code but make sure it’s also crystal clear. This will result in high maintainability and make it easier for people to work with you.

Yegor Bugayenko is founder and CEO of software engineering and management platform Zerocracy.