We all have horror stories when it comes to code. It starts off innocently until it morphs into Stephen King’s level of horror, turning the most optimistic among us into killer clowns.

While I can encourage you not to be that person, we still do it anyway or find ourselves knee-deep into something we didn’t exactly sign up for. Here are five chilling tales from my past and associated morals learned from the incidents.

Commenting Like I Know What’s Going on

The story:

Once upon a time, I encountered the code below, in a real live in production project.

//made a change here because Jay said so

The ensuing code made no sense as it used obscure x, y and zz values instead of actual names. I knew who Jay was, but he left the company three months before I chanced upon the code.

The moral:

The point of code is to act as a communication tool between developers. Machines’ ability understand the code is also part of the equation, but humans are the ones that consume code in its current linguistic state.

Good code is said to be self-containing and self-describing. But sometimes comments are required because they enrich the current code. They expand on context if it’s not clear due to constraints and abstractions. They are statements of fact that are not obscure when reading them.

The Most Logical Pyramid of Doom

The story:

It started off innocently with an if else statement inside a function. It didn’t take this code’s developer long to begin nesting inside of another if else statement.

The code then got passed around and another developer decided to contribute to the growing nest rather than refactor it out properly. By the time I got hold of it, most of the left hand side had been indented to a point where the actual code lived on the side scroll.

It was bad but it made sense — 30 minutes of tracing and backtracking later.

The moral:

Pyramids of Doom are called pyramids of doom because they’re built on unstable ground. SOLID principles are ignored and are often the first signs of lazy coding.

When code begins to nest, one needs to address it right away — even if it’s not your code. If you’re working on it, then you are responsible by association. If you’re not quite sure how to refactor out deeply nested code or prevent yourself from writing one, here’s a quick and concise guide.

When Real Names Matter

The story:

During my second winter as a fully fledged developer, I encountered a strange variable called cusboolmemtra which was inside a function called tracalent.

Names like these were littered throughout with no comments or references to what they really meant. A few days later and only after having lunch with the analyst did it start to make sense — they were abbreviations for parts of the database.

The moral:

Write your code like how you would talk to a real person. Call it what it is. Not everyone has insider knowledge. Good code is explicit in what it wants to achieve and what it represents.

We are supposed to be talking in the same language after all. Code isn’t meant to be a secret language that only the initiated is allowed to understand. Code is a communication tool, so use it to communicate clearly and succinctly.

Make It as Flexible as Possible!

The story:

The boss didn’t know what he truly wanted. Marketing didn’t know exactly what they wanted either. In fact, no one knew what they wanted but we just had to start coding — because coding takes the most time.

So we started tapping away with all the possible outcomes in mind. The idea of keeping everything as flexible as possible sounded great at first, until it came time to use the actual thing we created.

The code became too unfocused and eventually started to crack under the pressure to be as “flexible as possible.”

The moral:

Flexibility isn’t a bad thing, but code is a translation of rules. When rules are unclear, code is often unclear — which leads to leakage and potential holes in the expected output.

When code becomes too flexible, it has no clear meaning or purpose. Building a vague application will result in a vague outcome that doesn’t achieve anything much in particular. Names become obscure, classes become open for all and result in security risks, potential bugs, and breakages.

I’ll Come Back to It Later

The story:

The boss told us that we’d have time to come back to it later, but deadlines needed to be met and products had to be pushed out.

It didn’t matter if the code was perfect or not, just that it was functional and that it worked. Efficiency wasn’t part of the equation. Three years later, the application turned into a hack job that was built on promises of time that never materialized.

The moral:

Don’t trust anyone that promises you time. Treat the project like cleaning your house. Always put things away and chuck the things you don’t need. Refactor as you go so it speeds up your overall workflow rather than writing shoddy code in hopes that you’ll get time to think it out at the end.

Because there is no end.

A business will always want to keep moving forward, and as a developer, you also need to make it work for the code too.

Let’s Test Everything

The story:

Someone got wind of test-driven design and decided to make everyone write testing units. Except the team didn’t really understand the concept of test-driven design.

There was the testing part and the designing, but the driven was missing. Everyone wrote tests that didn’t really do anything in particular except for testing if inputs equated to outputs.

It was rather boring and did nothing to the overall workflow except take up more time.

The moral:

TDD is more than just writing tests. The core concept behind TDD is to test scenarios — that is, real life scenarios that are not rooted in a particular input or output.

Code’s purpose is to translate real life rules into “computer speak” for machines. It is these rules that one should be testing in TDD — not if a function will spit back a certain return.

Write tests that support the overall business rules that you’re trying to implement — not the other way around.

Final Words

Every developer who’s been in the field long enough has some sort of horror story. Over the years, I found that approaching each tale with a calm and non-judgmental mind can help make or break relationships, along with reducing or increasing resistance from the dev who wrote the code.

It takes collaboration, it takes time, and it takes understanding to create a true masterpiece. It also takes a good amount of emotional detachment from code to create anything that is truly solid in its grounding and construction.

Not everyone writes perfect code the first time round — nor is there such a thing as perfect code. Just take a look at the code you wrote five years ago. Chances are, they were horror stories for someone too.

So don’t be too hard on your juniors or those who wrote the code before you. Take it in your strides. Enjoy the horror and be the solution it needs to end the story on a happier note for the developer that follows after you.