Computers run code, but humans read it!
Tags: javascript, programming, beginners, tutorial
Published: 2022-02-22 18:35:31

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:
```javascript
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:

```javascript
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:

```javascript
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`? `u`ser? `u`mbrella? 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.

```javascript
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!