Hard to Read Code is Not Empathetic

Prompt

You just finish creating a chain of composed functions with a higher order function wrapper that abstracts many layers of complex conditional logic behind a few function calls. It works, its decently performant, and it just got merged to master. The feature it supports works fairly well without a hitch.

A new edge case in one of the inputs is introduced that breaks your code. However, you aren't the one assessing the problem. A colleague notices it, and they are not nearly as familiar with or comfortable with heavy functional approaches. They struggle mightily to identify the problem, and come to you for help. You explain the entire process and how the composed functions work. You end up needing to implement the fix, which adds more complexity under the hood.

Your colleague points out that the logic could be dramatically simplified by a couple of if statements and one or two functions. Sure, it might not be as performant or might lead to having to account for a few more edge-cases, but it is easier to debug and read.

Empathy in Code

While my prompt is a bit specific (and in no way calling out functional programming -- I have no problem with the concepts in general -- I think it illustrates my point, that the harder code is to read, understand, and explain, the harder it is for other people to make changes to or contribute updates to your code. It's definitely a good idea to find ways to make you and your team better. But hard to read code is not the answer.

The more senior you are, the more vital it is to keep in mind some important questions when implementing code:

• Can I explain this code to someone who is less experienced than me?
• Can I explain this code to someone who is onboarding to my team?
• Can I explain this code to myself after not having seen it for a long time?
• If I add documentation for this code, is it spending more time describing the purpose of the feature set, or describing how the code works?

Less is more

We've heard this saying before. But I'm not talking about code in this case. I'm focusing on complexity.

We should strive to have code that is readable, maintainable, and resilient to change. Each one of these things is influenced by human factors - I'd argue that for all of them, the human factor is the most important one. If a feature set can be described and implemented with clear, straight-forward implementations that focus on fundamentals rather than more complex and advanced concepts, the former is the right decisions and approach.

Don't be put off by explicitness

Consider the classic example of adding an array of numbers together:

// Explicit

function sum(array) {
  let sum = 0;
  for(let index = 0; index < array.length; index++) {
    sum = sum + array[index];
  }

  return sum;
}

// Functional

function sum(array) {
  return array.reduce(function(total, number) {
    return total + number;
  }, 0)
}

I much prefer the first approach, which is very clear as to what the end result of the function should be, what variable is used to track the running sum, and how to iterate through the array to increment the sum. You could argue that some of the same approaches can be taken with the second approach, but that doesn't take away from needing to have the context of how reduce's callback function works (and then, what a callback is and how reduce uses it). It's a lot of added knowledge to perform a simple operation that people who have a lot of strength working with reduce take for granted.

Yes, the first example is easier to implement and thus, perhaps, a lot more basic. My argument for that is...so what?

Parting Thoughts

Code is the implementation detail of engineering. How you are able to expand, explain, and collaborate is where the skills lie. Easier to read code opens the door to more collaborative cultures and makes your team one other people will want to join. Embrace simplicity.