The secret guide to amazing code


October 04, 2017

Warning! Everything you’re about to read is purely my own opinion. Still, it will make your code better and should not question it. With that out of the way, let’s divulge the secrets :)


Writing nice, readable code is one of the reasons why I love to write code. It makes me incredibly happy to go back to a piece of code months later that I can easily read as if it was a book written for a 5-year-old.

Here are the confidential secrets to writing amazing code that leads to easy changes, fewer bugs, and will make you and your team absolutely delighted.

The problem

Everyone has a slightly different version of what amazing code looks like.

What is amazing code?

Here are the points I believe make better code:

  • Readability. Amazing code is be easy to read and understand. Why the code was written, its purpose, and how it works, should all be clear in the code.

  • Simplicity. Amazing code is not dependent on assumptions that can’t read in the code. Simple and amazing code is hard to use if you use it the wrong way.

  • Consistency. Amazing code is consistent all across the board. Its naming, file structure, and indentation should all be consistent. The style decisions made and paradigms chosen do not matter. Just be consistent.

So… How do you write amazing code?


Zero comment policy

Comments go stale and have a tendency to tell you wrong things about the code. Also, comments (for the most part) make it okay for code that is hard to understand to exist. Avoid using comments wherever possible. Instead, focus on making the code more readable.

// Bad code 😞

if (someNumber > 12) { // 12 means that we need to start swimming
   startSwimming()
}
// Amazing code 👍

const swimmingThreshold = 12
const shouldStartSwimming = (x > swimmingThreshold)
if (shouldStartSwimming) {
   startSwimming()
}

Zero TODO policy

Stop thinking that those “TODO” comments will mean anything. Be honest with yourself, nobody ever goes back to fixing those “TODO” comments unless there is a bug associated with it.

If you must absolutely have a “TODO”, then document it in some place where it can be seen by everyone. Ideally, in a project management system such as JIRA, Trello, etc.

// Bad code 😞

while (swimming) { } // TODO: we need to speed up this while loop
// Amazing code 👍 - just remove the comment and document the change somewhere!

while (swimming) { }

Self documenting code

Use the power of functions and variables to create self-documenting code. Function and variable names are an extremely powerful tool to express the intent of the code.

On variables: The “why” should be expressed by the variable name. The “how” should be told by the variable assignment.

On functions: The “why” should be expressed by the function name. The “how” should be told by the function definition.

// Bad code 😞

if (x > 2 && x < 5) {
   fireMissiles()
}
// Amazing code 👍

const enemyInRange = (x > 2 && x < 5)
if (enemyInRange) {
   fireMissiles()
}

Less indentations, please

The first line of indentation should be reserved for the “happy path”. In order to achieve this, you have to break early when a “bad” path is detected.

The most important part of the code should be in the first indentation of any given function.

// Bad code 😞

const getUsername = (id) => {
  if (id) {
    get('/username/' + id)
  }
}
// Amazing code 👍

const getUsername = (id) => {
  if (!id) {
    return
  }
  fetch('/username/' + id)
}

Immutable

Use const wherever possible instead of let or var in JavaScript.

When the value of a variable is understood, you don’t have to think about the value of that variable ever again. It will always have the same value which will bring less fatigue to an already tired brain.

// Bad code 😞

let result = first * second
if (result > 70) {
  result = 70
}
// Amazing code 👍

const result = Math.min(first * second, 70)

Another example:

// Bad code 😞

let myValue
if (number === 'one') {
  myValue = 1
} else if (number === 'two') {
  myValue = 2
} else if (number === 'three') {
  myValue = 3
}
// Amazing code 👍

const myValue = {
  one: 1,
  two: 2,
  three: 3
}[number]

One line of code per thought

Reading code typically requires a vast amount of concentration. Amazing splits complex lines of code into simple ones by keeping the “coding sentences” short.

// Bad code 😞

users
  .filter(user => user.age > 10 && user.firstName.length > 2 && user.lastName.length > 4)
  // wait... what?
// Amazing code 👍

users
  .filter(user => user.age > 10)
  .filter(user => user.firstName.length > 2)
  .filter(user => user.lastName.length > 4)
  // ah... much better

“Dude… the ‘amazing’ code has a worse performance than the ‘bad’ code. What is wrong with you??” Look, unless your application requires you to care about microseconds, you should always favor amazing code which sometimes is not the fastest, over bad code which is one microsecond faster.

What do you think? Are these things that you already do? Do you think I’m completely crazy? Whatever it is, let me know! The more we share, the more we learn :)

I hope this article was useful to you. Have a wonderful life!


Written by Victor Dozal who lives and works in Austin, TX. He enjoys building useful things, writing about his journey as an engineer, and consuming lots of coffee. You should subscribe to him on YouTube :)

Need help with your project? Struggling with a problem? I'm at your service.