It’s easy to think about programming as an exercise of computers, or of languages and design. But at its heart programming is just about people. I bring this up because it’s so easy to lose sight of the fact that people are who you’re really programming for, and I just need a reminder sometimes. Maybe you do too.

Computers Make More Logical Sense than People

I got into programming for the same reason that many other people like me did. By like me, I mean outwardly similar: socially-awkward, middle-class white males growing up in the United States in the 1990s. It was a place to do really cool stuff without having to deal with those messy people and their confusing preferences and agendas. I didn’t really comprehend people easily, but I could understand computers.

And whether you look like me or not, you probably think (like I did then) that programming is about computers. About how we can make them do cool stuff really fast and blow people away. I no longer believe that that is the use or purpose of software.

People Are Using Your Software

Software is written for people. Computers are tools that people use to accomplish goals, nothing more. Computers are completely incidental to the human goals for which software exists. And when we lose touch with those human realities at the edges of computer systems, we do both users and fellow programmers a disservice.

Consider Apple

I have a rather irrational love for Apple (Computer). And whatever you think about Apple, one of the things they have a history of getting (mostly) right is prioritizing the experience of the person using their products. Where many other technology companies are influenced primarily by what the technology enables them to do, or what they have a cohort of their customers fervently screaming for, Apple has a history of placing the individual user’s experience of a computer system before everything.

Apple’s hardly the only company which would claim to aspire to this ideal. But they are the one which most regularly has come close. (Which is also not to say that they never falters in a achieving it.)

In Which I Make An Unfair Generalization about Java

Every terrible and rightly reviled piece of “enterprise” Java software, every computer that works but doesn’t delight, every little website delivered with a “well it’s a little weird, but you have to just take these three unintuitive steps…” is a small but tangible disservice to the notion that people are at the heart of what we make software for.

There are sane and necessary trade-off that must be made in business. Not all of us can afford a team of designers working for a year to design the new Facebook Like button. So we cut corners, we make sacrifices, and people are served a little less well by the resulting product. There’s nothing wrong with making these trade-offs between what the software we’re making is enabling its users to do and what we can sanely make work given existing constraints.

The trade-offs we make in designing the user’s experience of and interface to our software are a great topic to consider. And I’m no expert on how best to thread that needle.

People are the Only Important Interpreters of Software

I’ve written about how you name things while programming, and how you can think about the stories your programs tell. And it’s only on reflection that I see I was driving a broader point: we should write our software not with a focus on making sure that a computer will successfully get it working in the way we want, but so that another person can pick it up and quickly make sense of it.

Part of that effort is enabled outside of your software. Quite simply, we humans need a good amount of education before we can really wrap our heads around some of thoughts that computers allow us to think. And syntaxes required to encode certain ideas and data structures into computers require some familiarity. We’re still probably decades away from sufficient structures of performant abstractions and syntax evolutions of programming languages that we could sanely expect any human off the street to pick up our program and be able to change it.

But those things said, that’s a goal that we too often dismiss entirely when programming: thinking about how we’re communicating the functioning of our dance with the computer (… er … program) to another human. Too frequently in software I’ve written and let lay fallow, or when I pick up something left behind by someone else, I’m forced to spend minutes or hours making sense of what exactly all these obscure names, syntaxes, and flows are meant to be accomplishing. And that’s a mark of code that could be made significantly better.

Here’s What You Should Do…

So in an effort to make your software better, here are some concrete thoughts I have about how to make your programs more decipherable by your follow humans:

• Favor explicit and unmistakable names — There are lots of ways you’re probably in the habit of writing poor names. I have a tendency to pick the typing speed of dsc over a longer and clearer download_stream_connection. Some people will do the my_thing dance, as if a future visitor will know what made mine unique. Look for places your names aren’t clear, and change them. (More on this in my article about naming.)
• Try to have a clear story for your program, and make sure it tells it — When your program goes through three distinct phases in the transformation of an amorphous blob of files to a useful collection for humans, its entry point should be a function or method that explicitly carries out each of those phases. Each phase can also be laid out clearly and in a place a person would expect to find them. (More on this in my article about stories.)
• Take testing as an opportunity to retell your stories — Automated software testing, when its done, is frequently done after the codes been written and the tests are just an afterthought that just make sure we test out our (poor) design. Names like testThatItHasACharacteristic are a symptom of that problem. Well-named and structured tests are a great place to see a software system in action, and they are a great opportunity to communicate the stories of your software. Treat them as such.
• Don’t fear the comments — I have a preference for making my names and program flows so clear and explicit that comments feel superfluous. But I also have a bad habit of falling short of that goal for a variety of reasons, and then leaving no comments at all. I still think it’s sane to feel that good code shouldn’t need comments, but if you don’t have time to make it so good your comments are superfluous, you should probably have some comments.
• Refactor mercilessly — Whenever you can, take a step back after you get a thing working and make sure you’ve done it well. The TDD teachers love to chant “red-green-refactor”, and with good reason. Whether you’re doing the deliberate practice of TDD or a more haphazard reload-browser-and-click-the-button style, once it’s working your software will benefit markedly if you take a bit of time and make sure that you clean up the ugliness that you created while you were just getting it to work in the first place.

Surely there are loads of other good ideas you should consider when you’re writing good software. But I do hope at least one of those gave you a bit of food for thought about how you can make your software better and more useful for the future human who is likely to be tasked with debugging it or adding new features. After all, until computers can themselves build new features and debug features programmed into them, human will always be the most important factors on either end of your software.

And remember, stay thoughtful!