Computers run code, but humans read it!

Coding is an activity that can go wrong from the very begginning of your applications.

You may find, as I have, that when working in a project that already exists, the code within will vary significantly from what you expect.

We all learn how to code from different sources, projects and experiences, and the more you learn about good practices in code, the more you will feel unconfortable with bad code.

When you're beginning every code seems smarter than yours, and complex code it's just "the way code grows"

Wrong.

The problem

Every machine can understand code, no matter how ugly it is, but humans are the ones in charge of reading, maintaining and expanding this code.

Code is written by humans, for humans. Computers are only in charge of running it.

Take for example:

const w = 1
const h = 2

function a(w, h) {
  return w * h
}

You an infer what's happening in this code, and a computer can read it easily, but what about:

const width = 1
const height = 2

function area(width, height) {
  return width * height
}

Now you don't need to infer a thing, the code is clear as water.

This may seem like you can go and infer what the code is telling us, but when complexity goes up, things get harder.

In a real world application, you will be working with API requests. Take a simple example:

const axios = require('axios')
const { url } = require('../constants')

async function get(id) {
  const u = await axios.get(url)
  const privs = await axios.get(url + '/privs')
  u.pass = undefined
  u.privs = privs
  return u
}

We can infer that url is the API URL, great. Now what is this function getting? get what?

Then we can see that we are storing a value in the u variable. What is this u? user? umbrella? You will have to console.log this variable to know what's inside, then you can infer.

What is privs, why it is appended to the u variable? At least pass property gives us a hint that this u may be a user with a password.

const axios = require('axios')
const { API_BASE_URL } = require('../constants')

async function getUserWithPrivileges(id) {
  const user = await axios.get(API_BASE_URL)
  const privileges = await axios.get(API_BASE_URL + '/privileges ')

  user.pass = undefined
  user.privileges = privileges 

  return user
}

Now I don't even have to explain the code. It can be easily read.

Solutions

• When writing variable names, go with the full name of the thing. Don't cut corners. Even longAndVerboseVariablesNames are going to be predicted by you IDE and you can simply tap enter to autocomplete them.

• When writing functions, again, go with the full name of the thing. Write them as verbs and try to be as specific as you can. This will make your code more readable for you and for your team.

• Try to separate code in paragraphs. As you can see I've added some spaces to the code, the first block is for API communication, the second one for assignations and the third is the return statement.

Final Note

This small function seems to be handling two responsibilities:

1. API Communication
2. Domain/business data manipulation

This should be separated in more functions, but that one is for another post.

Happy coding!