Be human-friendly

Nikolai Kim — Thu, 01 Sep 2022 14:00:57 +0000

While machines execute our code, they are not the sole or key audience we write for. The code we create should be easy to extend and maintain by other developers. Whether those developers are other-other, or just your future self.

I call this mindset being human-friendly.

Human Friendly Code is nice to read, easy to understand, and feels safe to change.

In this article, we'll have a look at four simple ways to implement this approach.

Introduce explanatory variables

Consider introducing variables to avoid code duplication or to make your code more expressive. In most cases, there’s no need to worry about extra bits of memory they would occupy.

function canEdit (user, document) {
  return (
    user.role === 'admin' ||
    user.role === 'editor' ||
    document.owner === user.id
  )
}

function betterCanEdit (user, document) {
  const isStaff = ['admin', 'editor'].includes(user.role)
  const isOwner = document.owner === user.id

  // The general idea is now expressed in a single statement ✅
  return isStaff || isOwner
}

Keep naming consistent

In general, you should aim for code that is easy to follow, so make sure your entities keep their names. The next snippet shows a bad example: it’s unclear if user and client are the same thing.

function verify (user) {
  return user.id > 0 &&
      user.name !== ''
}

function print (clients) {
  const data = clients.map(client => ({
    ...client,
    status: verify(client) // ❌ Clients suddenly turn into Users
  }))

  console.table(data)
}

Avoid unexpected behavior

From my experience, this usually comes from functions that mutate arguments. For instance, while this function does mix the elements of a list, due to .sort method it uses internally it also changes the original array, which may not be anticipated.


function shuffle (list) {
  return list.sort(() => Math.random() > 0.5) // ❌ Elements are sorted in-place
}

function betterShuffle (list) {
  return list
    .slice() // ✅ Make a shallow copy first
    .sort(() => Math.random() > 0.5)
}

Use simple statements

Making code all dense and terse can be a fun exercise. While the result may look cool, it would require more time and effort for others to understand.

const modules = {}

// ❌ We assign and return value in a single statement
function loadModule (name) {
  return modules[name] = modules[name] || loadModule(name)
}

// ✅ This code is straightforward and reads nicely from top to bottom
function betterLoadModule (name) {
  if (modules[name] === undefined) {
    modules[name] = loadModule(name)
  }
  return modules[name]
}

Well, these are the four insights on making human-friendly code that I wanted to share with you. There is no need to follow everything at once, if you aren't already. Just pick the idea that resonates most with you — and see how it goes.

Thank you for your time 🦊
Object Required

Forem: Nikolai Kim

Be human-friendly

Introduce explanatory variables

Keep naming consistent

Avoid unexpected behavior

Use simple statements