DEV Community

Cover image for Software Development for Humans
Bastion Fennell
Bastion Fennell

Posted on

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

Extra clever mousetrap

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!

Top comments (5)

Collapse
 
jaymeedwards profile image
Jayme Edwards 🍃💻

Great article. I love your attitude! You might also like my YouTube channel “Healthy Software Developer” where I’m trying to share strategies for development cultures that are healthier for the people doing the work.

I also post here on dev.to. Keep sharing your thoughts - we need better working conditions for programming!

Collapse
 
bastionthedev profile image
Bastion Fennell

Thanks! I'll definitely check out your channel! development ergonomics and mental wellbeing are super important to me, I think it's easy to lose sight of those things in the mad dash to push features out...

Collapse
 
jaymeedwards profile image
Jayme Edwards 🍃💻

Awesome. Yeah it’s really up to us to stand firm for quality work and reasonable commitments! No unethical leader ever changes their core motives from a conference talk 🤣

Collapse
 
gtanyware profile image
Graham Trott

Isn't it interesting that while you're in the zone it's like being in a dream that contains wonderful truths, but you wake in the morning trying to hang on to some part of it that still makes sense and it just isn't there. You might produce great code but that's of little use if you can't figure it out later. And if you have trouble, pity the next guy.

Been there, got the T-shirt.

Collapse
 
bastionthedev profile image
Bastion Fennell

Haha, right? When things seem to just make sense in that flow, it feels like you don't need to document anything. Then it's immediate regret the next time you look at the code...