Software Development for Humans

// Be wary ye who venture into the depths below
// Here be dragons

It's a programming tale as old as time. You jump into the codebase, ready to be productive and push out a bug fix. The ticket was estimated at one day of work, should be easy to knock out.

But no.

The further you dig into the code, the less you understand it. You feel like you're taking crazy pills.

How did this ever work???

Someone is to blame for this... Who could have done it? You pop open your terminal, it's time to figure out who to git blame. Your heart skips a beat as your trusty terminal seemingly turns on you...

Bastion Fennell 2019-02-22 10:44:36 -0600

It was your code this whole time!

Developer Empathy

When we're developing software, especially in industry, it's easy to only think of one end user: the customer. While this isn't necessarily a bad viewpoint, I'd like you to think about one more end user: the next developer. Specifically, the next developer who is going to be working on this piece of code. Especially because it's likely that next developer will be you.

To build software for humans, we have to start to gain a little bit of empathy for that next developer.

Empathy
em·pa·thy
/ˈempəTHē/
noun
the ability to understand and share the feelings of another.

To develop that empathy, we just have to put ourself in the shoes of the next developer. Which should be easy, because we've all been that developer. We've all worked in existing codebases and had to figure out what is going on. While Developer Empathy is something you'll be honing your entire programming career, here are a few concrete techniques to make the next developer's life easier.

Don't be Clever

As developers, we have a drive to try new things and patterns. Sometimes, these new things that are exciting to us aren't exactly clear to everyone else. When writing code, we want to make sure we're writing readable code instead of the smallest, fastest code possible.

Of course, if performance is a huge concern or specifically what you're working on, you may still have to write some clever code. You may actually need obscure APIs or complex single line calculations. For the most part, though, being a little clearer with our code and our intention with the code will make everyone's lives a little easier.

This leads nicely into my next tip:

Verbosity Over Brevity

for(i=0;i<100;)document.write(((++i%3?'':'Fizz')+(i%5?'':'Buzz')||i)+"<br>")

FizzBuzz, as written here in JS. Sure it works, and it's neat to look at, but it's almost impossible to understand at first glance. This is more a subset of "Don't be Clever", but it's important to be conscientious with how we name things and lay things out in our code.

for(i = 0; i < 100; i++) {
    const fizz = i % 3 === 0;
    const buzz = i % 5 === 0;

    if (fizz) {
        document.write('Fizz');
    }

    if (buzz) {
        document.write('Buzz');
    }

    if (!fizz && !buzz) {
        document.write(i);
    }

    document.write('<br>');
}

I'm not saying my code or implementation here is perfect by any means, but it's at least understandable. If someone was given a ticket to print Baz every time the number was divisible by 7, it would be super easy to do it. Being more clear in your intention when writing code is a way to think of the next developer who is going to have to understand that code.

Documentation

My final tip is the same tip that everyone will tell you and hardly anyone will do: Add more documentation.

// Document, document, document!

Sometimes, code has to be complex. Sometimes it's hard to see where this console error actually came from. Sometimes you know that what you are working on will be used by a lot of people.

In all these cases, try to add enough documentation to make it easy to understand. When you're writing the code, you have all the context for the problem. At least, you have most of it. Try to think about what parts of that problem will be hard to understand for the next developer, and add that in the comments somewhere.

Here Be Dragon Slayers

There is a lot more to consider when writing software for humans, but hopefully this will give you a good starting point! Together, we can go from just finding dragons to being dragon slayers!