Table of Contents
programming is a human concept, creation taken into the domain of the computer. creating is chaotic; it often makes a mess, and independent of whether you are super clean or not, it is a guarantee that at some point it will be messy. then, as things usually go, the weight of tidying up is always deposited somewhere, usually a person, who has to de-spaghettify the mess.
that person should be you (or however created the mess).
coding responsibly is important because it shows accountability and makes the quality of your code better, so that those who stumble upon it can also make use of what you wrote. programming is equal parts writing and logic, and if no one can read it, less will they be able to reason with it.
we all manage mess to some degree; we clean our spaces, throw trash in the bin, groom ourselves. code should be no different. making a mess and not tidying up is often a behavior seen in toddlers. you're not a toddler. tidy up.
what is mess exactly #
mess is whatever introduces unpredictability to your code. some examples include:
- badly implemented functions or untested features.
- quick "fixes" without doing root-cause discovery.
- inconsistent syntax.
the above examples all fall under the umbrella of "bad programming practices", however "the unpredictable" doesn't only cover your code's functionality, it also implies good maintainability, i.e. the ability to sustain the code you wrote as time goes on. some examples of mess in this category are:
- non-descriptive variable names.
- lack of useful comments.
- poor or non-existent documentation.
- bad PR, commit, issue messages.
as many things tied to our life as humans, code also follows a life cycle. it's conceived in an idea or a problem that would benefit from being solved or automated, it develops in pseudo-code or early versions, it gets released and tested, and it grows via new features and through its environment if it's accepting contributions.
it will eventually die (ideally) once a newer, better program solves the problem better or faster. however, as humans, it can also die prematurely. it can be so hard to read or so obtuse to use that it sees no activity, or worse, goes unmaintained for long periods of time, accumulating mess and falling into abandonware.
I'm not going to get into the ethics of "the life of code" as that is beyond the scope of this article, but the point stands: messy code dies early. avoid killing your code. tidy up.
what makes mess is bad, avoid it #
I recently came across a neat corporat word: result-driven development. basically "focus on the output, I don't care how you get there". this is terrible because it is inherently messy. pursuing a goal with no regard for the process, specially in programming, is a terrible idea. as Beej so elegantly puts it:
"Programming ain’t about writing code. [...] I would argue that solving programming problems does not involve a computer."
programming is all about effective problem solving, and "effective" implies "efficient". messy and unmaintainable code are antithetical to efficiency. be smart. be efficient. tidy up.
slop machine mess #
AI is often called "slop" because it's a mess generator. whatever prototype you get from it needs to be immediately tidied up. if you use it, congrats, you have now been reduced from "effective problem solver" to "border control person whose job is to tidy the slop machine's mess". I take pride in my work, and so should you. if not, you risk sounding like this:
"b-but ked I use AI to help me solve the problem!!1 I swear it's real good and 20% of the time it works 100% of the time. I also huff glue regularly."
AI is not an effective problem solver, like, at all. AI is not a calculator, and was never intended to be. it is not a predictable tool. it is a plagiarism regurgitator, with a tendency to hallucinate, giving you a really bad fix to your problem and creating even worse mess in the process.
to be an effective problem solver, it's imperative to understand that there's also myriad ways to solve a problem, and some will even change depending on how you choose to solve them. if AI does your thinking for you, then you're the target metric when they say "AI will replace ...". if you want more reasons to hate AI, go read this, but in essence, do your own thinking. implement your own solutions. tidy up (your brain).
untidy mess creates debt #
we are all guilty of making the classic filename.old.bak.1.working.new shenanigans. it's fun for the first few files, but once you're managing an entire infrastructure or you're running a server for more than a week (I'm looking at you, compulsive self-hosters) you immediately know it's unsustainable.
when it's your own server, it's ok... for a bit. worse case scenario you docker compose up'd the bad file and now some services are fucked, and you gotta remake them, and restore... uhhh, what backup was it again? bkup.1.old or backup.full.old? wait, let me check, I'm sure I noted it down... what command did I use...? let me check my notes. where are my notes?
see what I mean?
it's even worse when you actually work with people or have to log into shared servers, and then, either you or a worse-off intern has to tidy up the mess. best case scenario it's just diff-ing some configs here, rewrite a bit there... worse case scenario, congrats, you're fired, because we hired someone else to rewrite the entire thing, just that they actually do the work well. why did they hire you again?
if you're going to create code to solve a problem, it should actually solve it, not create more problems. if you also want that code to live on and be useful, then it should be tidy. else, the mess you created will either come back to haunt you, or some other person down the line. code responsibly, tidy up.
managing the mess #
we all know the mess branch in our version control software. it tends to be dev, or testing. maybe you're more original with the naming, but the point stands. it's the programming equivalent of putting plastic covers around your room and emulating Jackson Pollock with whatever paint you could get your hands on.
but you keep main, or prod, or whatever else off the mess branch. you go off do your messy thing then come back. also it may not have started clean, like re-painting the walls of a house you bought from a guy named Jackson or something... but once it is clean it goes to the clean branch, and experiments go to the mess branch.
another way to handle mess is via documentation. for example, an obtuse, weirdly named function was created in a time way before you, and changing it may create more mess? then document it! a simple explanation of what it does will suffice, so that others that come across it won't have to scratch their heads or cover their eyes.
if you can't erase mess, or weren't in charge of mess from the start, then you get to tidying up where you can, and avoid creating more mess elsewhere. sometimes the solution is just "mess control", until a better solution can be found. other times, you're forced to clean up someone's mess and rewrite entire codebases, and you end up writing a blog post about mess. things happen y'know?
it is important to note this: I am not a clean code purist, as much as this post may suggest otherwise. mess is inevitable, it will appear at some point, and it is healthy that it does, but you need to keep it to the line. at the end of the day, you need to code responsibly, and that means you should manage your mess. tidy up.