What is Code?

First and foremost, without a doubt, code is written for humans. Computers read binary data, machine instructions, which load data into a CPU buffer and transform it. By the time a CPU is reading the instructions you wrote, you wouldn't recognize them at all unless you've spent a great deal of time studying assembly language.

The programs written by humans, the actual text files, will be translated beyond recognition in order to be executed by a CPU. So what is code?

Humans don't think the way CPUs do. Some of us can, and those that can are usually programmers. However, it doesn't suit us. Humans think in abstractions, which, if you ask a Zen master, is also wrong, but it does have its advantages in solving problems.

Writing code is the first step in translating human thought abstractions into machine instructions. In between the text files written by a programmer, and the binary executable run by the user, there are many layers of translation that turn code humans can understand into code that machines can understand.

Code is text for humans. Code is only ever read by a compiler or an interpreter, and by other humans. As long as the code is valid, the compiler or interpreter doesn't care what the code looks like, or how readable it is. But other programmers do.

I write code to automate. I write code in order to create a button that, when pressed, creates value in our world. This value can arise from automating repetitive tasks done by other humans. It can arise from creating an optimized process that when followed, help a group of humans to accomplish an objective. The button might take a set of data and distill it into conclusions that can be used by humans to make decisions at a glance. A button can perform a calculation in the blink of an eye that might have taken a great mathematician many days to solve.

Code is Time.

Humans write code to save time, to create time, an otherwise extremely limited resource given to us moment by moment from god itself.

If you write a program, chances are, it's saving time. How much time is it saving?

• How long does it take to execute the task manually? δ_m
• How long does it take the program to execute the task? δ_a
• How long does it take to develop the programmed automation? δ_d
• How often is the task executed?
• For how long will this task execution schedule remain in effect?
• How long does it take to troubleshoot the code?
• How long does it take to modify the code?

These are the considerations one might take into account when attempting to measure a program's efficacy, the ability to save time.

I'd like to focus on the final item in the list to ask a question to you, dear programmer.

How long does it take to modify your code?

Say that you've written a bit of code that saves the intern an hour each day by reading a spreadsheet and transforming it into a report which is then emailed to your manager. It took you 10 hours to write the code on your first go-around.

But then your manager asks the automation to perform a new function.

"Okay," you say, "No problem. Let me just have a look here... and... wait, what on earth does this code even do?"

Sound familiar? We've all written code that, upon revisiting, makes no sense to anyone, even the person that wrote it.

Now you, dear programmer, are in a situation where you have a choice to make. Do you:

• Start from scratch?
• Fix the existing code?

If you're asking yourself this question, it is likely that the original code base was no well-architected. It was not sufficiently designed to easily adapt to the future.

It is at precisely this moment in every programmer's life where they realize there is more to writing code than just accomplishing objectives and saving time. There is architecture and engineering within the codebase itself. There is time to be saved in the writing of the code itself.

Programming Craftsmanship

The reason code becomes unreadable, even by its author, is because programmers are too clever for even themselves. They find a novel solution to a problem in only a line of code, which takes full advantage of the programming language's features, combining several syntax shortcuts into a mess of code that might take 30 minutes for a human to fully unpack.

For example:

lambda n:`n`+'tsnrhtdd'[n%5*(n%100^15>4>n%10)::4]

As a person proficient in python, I knew what the function did, I even used it, but I couldn't understand how it worked. The creator of this code snippet is obviously quite skilled, and probably even knows what I'm about to say, but if one of my developers was ever caught putting code like that into my production codebase, they'd be asked to find employment elsewhere.

Craftsmanship in programming starts with the understanding that code is written for humans.

If I can't figure out what your code is doing at a glance, it's wasting my time. Why? Because it's easy to write easily understandable code at a glance.

But it's boring. And it takes a lot of forethought and discipline.

You're also likely to find yourself halfway done when you realize your code is not well-architected, and that you now have to consider whether to:

• Write a bit of a hack here to make it work so you don't have to start over
• Start over and do it right this time around

Quite simply, a true craftsman in programming has no problem doing the latter. The craftsman wants to be able to sleep at night, knowing that their future is free of encountering that situation where someone finds out about the hack they left in their code. The craftsman is not lazy, and will start over if that's what it takes to create a quality product. The craftsman is not emotionally attached to the code they have already written.

Well-Crafted Code

It takes discipline, care, and selflessness to write well-crafted code. It takes attention to detail.

• Doc strings are boring and repetitive, but it will save time for a new developer starting on this code base.
• Descriptive naming conventions take longer to type than function, class, and variable names that are short and make sense to you but probably no one else
• Many simple, well-named functions that do a single thing well are better than stuffing a project into a single function that consists of many nested loops and logic trees

Code is for humans. While I, as a programmer, have the capacity to hold the many spinning plates of a program in my head to simulate code execution, it is difficult. Writing code in a way that requires many spinning plates was not written for humans, but instead for CPUs. A CPU can handle more spinning-plate loops than a human ever could. Every time this type of code is revisited by myself, or by another developer, they have to read the code and start spinning the plates themselves. And then a coworker knocks on your cube and all the plates fall down and break.

Craftsmen write code without spinning plates. They save time with how they write code. It is clear from a glance what a block of code does, and after studying the codebase for a few minutes, it's clear how the codebase is architected.

Troubleshooting Code

Well-written code breaks quickly and loudly. Specific exceptions are thrown. Proper logging is implemented.

To re-iterate, code is written for humans. Code executes inside a black box, so craftsmen have to build their house with plenty of windows to see inside, to show others what's going on.

Simple code that is written for humans breaks less, but just as importantly, it is easy to fix. Any auto mechanic will tell you that it's better to fix a part that is easy to get to than one that requires taking apart the whole car. Car engineers are simply unable to make every part easy to get to, due to the limitations of physical space. Programmers, on the other hand, can put every single part of their car within easy reach of the person troubleshooting it.

Code Craftsmanship

At minimum, a programmer can write code to do whatever a computer can do.

A craftsman is distinguished from a mere programmer because they take the time to ensure that their code is accessible by the other developers working on the codebase.

The time invested up front will pay dividends over the life of the project, something most management will never understand.