on simple code

Posted on Fri 08 December 2017 in code

As I get older, I have started to notice how many of my childhood habits that I assumed had been useful and intelligent were in fact, horrible ones. All of these fancy words I had thought made me look smart, in actuality, often just made me seem like an egotistical show-off. At best they served only to confused the people I was trying to persuade, and at worst these ridiculous words ended up completely alienating them. Unsurprisingly, the same is true for code. Simple code is easier to maintain. Simple code is easier for you to understand later. Simple code is, to put it simply, better code.

Simple code is easier to maintain.

No matter your environment, unless you never, ever, plan to share your code with anyone else (boring!), the fact of the matter is that your code will at some point be someone else's problem. Maybe it's part of an open source project or maybe it's enterprise code, but regardless, at some point there will be someone else looking at and having to maintain your code. How will it reflect upon you if your code is horrible to dissect and understand, or if your code is full of ridiculous flourishes of programming one-liners that scream, "look at me, I know what a closure is and I'm not afraid to use it!"?

Consider the code:

#include <stdio.h>
#include <stdint.h>

int main(int argc, char *argv[])
{
    double magic = 7.949928895127363e-275;
    uint64_t not_magic = 0x0706050403020100;
    /* assuming 64-bit doubles */
    printf("These are the same! %#.16lx == %#.16lx", *((uint64_t *)&magic), not_magic);

    return 0;
}

To solve some problem where you may happen to need the constant 0x0706050403020100, is it really necessary to use the double version? Maybe you think the double version makes you seem more intelligent, but really all it proves is that you are a show-off. Whenever you find yourself writing code that may look a bit obfuscated or questionably strange to others, you should always be asking yourself:

"Was there really anything gained by this?"

At the very least, add descriptive comments describing for the unsuspecting programming who must read your code explaining why you had to inflict these atrocities upon them.

Simple code is easier for you to understand later.

You may be the smartest person in the world, but that doesn't change the fact that no matter how well you may understand your fancy spaghetti code now, you will definitely not understand it as well two months from now. Complicated code is just that; complicated. It requires, by definition, more cognitive attention to process, and yes, you may possess that degree of attention now, but will you later on when the code is no longer fresh in your mind? A better question: even if you will, would you want to have to spend that amount of attention on doing nothing more than understanding your own code?

I am just as guilty of this sin as anyone else; one of the regular expressions used in a REPL project of mine (this is a bastard of a regex that I am still trying to figure out how to do away with sanely and still have my program behave the same way) is:

char const middle_regex[] =
    "(^[[:blank:]]*|^[^,(){};&|'\"]+)"
    "(struct|union|_?[Bb]ool|[rs]?size_t|u?int[0-9]+_t|ptrdiff_t|"
    "intptr_t|intmax_t|uintmax_t|wchar_t|char[0-9]+_t|"
    "char|double|float|int|long|short|unsigned|void)"
    "[^,(){};&|'\"[:alpha:]]+[[:blank:]]*\\**[[:blank:]]*"
    "([[:alpha:]_][[:alnum:]_]*)[[:blank:]]*"
    "([^,(){};&|'\"[:alnum:][:blank:]]+$|;*$|\\[|,)";

Gross. Do you really think it's pragmatic to force that upon yourself a couple months down the road? I sure don't.

Simple code is, to put it simply, better code.

"Why should I bother making my code simpler?" Ironically, the answer is also quite simple.

The simpler your code is, the less bugs it has, the faster it runs, and overall, the better it works.

Complexity breeds pain, and you pay the cost in hours of debugging, in performance hits, and in an affront to your very sanity. A nice example of the opposite can be found in one of my favorite unit test frameworks, libtap. The entire codebase is concise, descriptive, and to the point.

One of my unit test files (modulo variable declarations) is nothing but:

plan(3);

lives_ok({pipe_fd(-1, -1);}, "test living through pipe_fd() call with invalid fds.");
dies_ok({compile(NULL, NULL, argv);}, "die passing a NULL pointer to compile().");
ok(compile(src, cc_args, argv) == 0, "succeed compiling program.");

done_testing();

Even for someone who doesn't know C, what is happening is so obvious it's almost criminal. The code has very obvious semantics, it does exactly what is expected of it, and it takes nearly zero effort to mentally parse.

If you make the effort to strive towards writing code that takes as little effort to understand and maintain as is realistically possibly, you will may not notice anything meaningful at first. However, after just a little while, you will find yourself pleasantly surprised at the net effect it has on your code.

Your code will end up containing far fewer bugs.
Yout code will win you the affections of your managers and coworkers alike.
And all-in-all, your code will end up costing you far less of your sanity.