thinkingincode.ninja [Dark]

What is "clean" code?

Suggested previous reading: Effective Coding: Series Intro

I'll get right to it. There's code that's nice to read, and code that gives you a headache when you try to read it. I'm going to go over what makes code readable, and what makes it have that headache-y quality to it.

Disclaimer

Now, I feel it's important, before I talk about what makes code readable, to say this: My intention is not to make you feel bad about your code or your skills as a programmer. Anything I say you "shouldn't" do, I have done, and I have probably done it many times, and to be honest, I probably still do it on occasion. If I use examples of bad code, they are samples of my code, because it's not fair for me to judge someone else's code and put it out there, at least not without their express permission. Further, I'm not saying that I am right about everything (though there are some things I'm reasonably confident I'm not wrong about), and that there is no other way. If you think I am wrong, then by all means let me know; I'm very open to hearing where I may have made an error in judgment, as it gives me the chance to reflect and grow. My goal here is to lay out a set of rough guidelines, to serve as reference for those who need or desire them, or to initiate self-reflection.

Clean code

Now that that's out of the way... Clean code. This post is going to go over the "what" and, to a large extent, the "why"; later posts will go over the "how". Here, I want to lay the foundation for what I mean when I reference the idea of "clean code" on my site.

I think there are five broad principles behind clean code:

  1. Names are important
  2. Intentions should be obvious
  3. Code should be organized
  4. Repetitiveness should be avoided
  5. Cleverness in moderation

Names are important

Let's start with the first. The computer doesn't care what you call your variables, how you name your classes, etc. In the end, the computer is going to convert your code into something it understands, and leave out all the unnecessary information. Names thus exist for the person reading the code, so it follows that names should be chosen so that it's clear what is going on; part of this is using accepted naming conventions, part of it is choosing the right name.

Intentions should be obvious

This leads into the second, yet distinct, point, which is that intentions should be obvious. This goes beyond just naming things, into writing code that's not intentionally misleading. This means using the function IsAdministrator to check if someone is an administrator, not to delete all files from disk. The purpose of code is to do something, and there's little sense in giving someone the wrong idea about what your code does. Oh, and yes, part of this does mean leaving at least the occasional comment in your code.

Code should be organized

In the same vein, code should be organized. Scattered code is hard to follow, and hard to follow code means it's easier to miss bugs, and just makes life harder in general. Organized code means that like code is in like places, that it's easy for people to find things in your code. Consistent and well-organized code allows you to rapidly and effectively navigate around the codebase even after extended breaks from the code.

Repetitiveness should be avoided

Another principle is that you shouldn't repeat yourself; you may have heard this as the "DRY" (Don't Repeat Yourself) principle. Basically, you want to avoid typing the same code pattern over and over again. If you have duplicate (or basically duplicate) code, then, at minimum, it gives you more places to make a mistake. Usually though, if you have duplication in your code, the main impact is that it takes more work to make changes, because you have to duplicate your changes in multiple places.

Cleverness in moderation

Finally, cleverness is great, but in moderation. Solutions can (and should) be clever, but your code should be as straightforward as possible. It's often better to favor readability over extreme optimization. Computers now are fast enough that you probably don't need to intentionally try to squeeze every last bit of performance out of your code. Now, this doesn't mean that you should intentionally write slow code, because that's not really very productive. But if you're at a point where you are optimizing your code at the expense of readability and maintainability, it wouldn't hurt to pause and ask if you really have to keep optimizing.

Why it matters

"That's all well and good, ninjattic, but why should I care how readable my code is? It works, isn't that what really matters?" you might be asking. And it's a fair question.

Unless you are writing code that you will literally only run once (and even then), chances are pretty good that you'll be looking at that code again. And when you do, chances are pretty good that you'll be looking at it because you want to change it. When that happens, you'll find it matters greatly how readable your code is, because the more readable your code is, and the easier it is to understand, the easier it'll be for you to make the changes you need to and move on. Or, if it's not you who is making changes, it'll be a co-worker, or someone who comes after you. Maybe it's just someone who wants to read your code to learn how to do something. Regardless of who it is who is reading your code, you should be nice to them. Eventually, you'll be in a position where you're having to read (and maybe even maintain) someone else's code, and when that happens, you might be wishing that they had read this post too.