Certain programmers believe that code should be self-explanatory. These programmers give various reasons for not documenting their code. Yet these reasons often involve logical fallacies and cognitive dissonance. Here’s why the advice to “write cleaner code” is a fallacy.

Humans Aren’t Machines

The Evolution of Programming Languages highlights how programming languages are used as interfaces for humans to write machine code in an efficient manner. The significance being that programming languages are created to be human readable, rather than optimized for machines. This distinction has a variety of implications on a program’s performance.

When a human performs a task, the brain uses a variety of cells and signals to make a decision. When a machine performs a task, its decisions are the result of a configuration of electrical switches (which represent 1 or 0). Both a human and a machine can answer the question, “What is 2 + 2?” However, the optimal approach for each entity will be different.

Programming languages provide abstractions that let humans translate their language into optimal machine code. However, it’s still up to the human to provide an optimal order of operations for the machine. Those who rely on “writing cleaner code” assume that “clean code” is always equivalent to code which results in the maximum performance of a machine.

For example, the Binary Search Algorithm is the fastest search algorithm for a machine, but not a human.

Lines Of Code Doesn’t Determine Quality

Does the amount of Lines of Code (LOC) a program has matter? When it comes to using LOC as a metric, you’ll find programmers up in arms stating that “LOC doesn’t matter.” Yet it doesn’t take long to find various comments by the same programmers saying that “the best programming solutions maintain the least lines of code.”

So which one is it?

Let’s consider the Binary Search Algorithm again. A for loop is a solution to the search problem that involves less code. Yet this solution is not as performant as the Binary Search Algorithm. In this case, more code results in better performance, but this doesn’t mean that writing more code is always better. More so that the “amount of lines of code” a solution maintains doesn’t indicate quality.

Less Lines, Less Logic

Humans use code logic to implement business logic. So it’s not surprising that complex businesses require more code. What proponents of the “less is more” crowd forget is that their code represents a set of instructions. In doing so, complex problems are solved with “simple solutions” that result in errors (by missing edge cases).

An if statement is a conditional statement in human language that determines which action to proceed with upon a given condition. When a manual procedure maintains conditional statements, programmers automating said procedures can NOT avoid the usage of the if statement: Implementing the manual procedure correctly will require an additional line of code.

Import Hypocrisy

The goal of Code Golf is to solve a problem using the least amount of characters possible. It’s often that code golf solutions involve standard library functions and other symbols which import code from other places. Have you ever seen a Python “one-liner”? This is the end goal for low LOC maximalists. Yet the existence of these one-liners aren’t possible without importing a great amount of code. These programmers maintain cognitive dissonance by ignoring the fact that they use more lines of code by preference.

Documentation Isn’t The Issue

There exists a class of programmers who refuse to write documentation for anything they work on. It’s often for “cleaner code advocates” to fit this demographic. Certain advocates against documentation state that it’s a waste of time since, “The documentation becomes outdated.” Yet I find that these people confuse “outdated” with “unread” because these people don’t like to read.

On the off chance that you get this person to maintain documentation, you’ll find that the above point becomes true (with regards to their own documentation). That’s not because it’s inevitable for documentation to become outdated, but because the anti-documentation advocate doesn’t update their own documentation. If these advocates were politicians, they would defund governmental programs, then point out how these programs are inefficient.

Yet the worst part of working with programmers who fail to provide documentation is when their “clean code” ends up being not-so-clean. So now you have to track them down through the dimensions of time and space, hoping that they’re mentally ready to answer your question. Everyone gets blocked. All because someone didn’t want to waste their precious keystrokes.

You ask them for clarification on their code. Queue five more minutes of waiting as they decipher their squeaky clean logic. The pressure weighs down on their soul, so they tell you to “read the man”. Who the f*ck did you think wrote the man? I. am. the. man. Anyways, the person tells you that it’s obvious what the code does by the variable WKW, which represents an acronym for who knows what. You’re not a mind reader so you ask what it means, only for them to argue about the semantics between a deque and circular buffer (when they are the SAME THING).

GAHHHREFHERTHGHEJ. JUST LINK TO WHAT YOU’RE TALKING ABOUT!

One of these programmers once asked me, “What’s the definition of the bozo variable that’s littering the codebase without comments?” Then I pointed at him. He started adding comments later that day… If I have to coordinate a meeting — by factoring your time, my time, a place, and mental availability — on a calendar to get clarification on your code, I don’t want to work with you. If you are a programmer who doesn’t write comments, I hope you are forced to make IKEA furniture without a manual. Documentation isn’t useless. Your reading comprehension is sh*t!!

Write comments for your code.