Write code humans can understand

To write code that other programmers can understand is a hard task that only 20% of the programmers have. When you are writing software, you can’t only think if the machine can read, but also if the humans can.

“Any fool can write code that a computer can understand. Good programmers write code that humans can understand.” — Martin Fowler

Clean Code: A Handbook of Agile Software Craftsmanship, written by Robert “Uncle Bob” Martin, explains more of the concept of programming for the code readers. This reader may be:

• The future you
• Your co-workers
• The machine

You have to write code that these three can understand or maintain.

Even bad code can function. But if code isn’t clean, it can bring a development organization to its knees. Every year, countless hours and significant resources are lost because of poorly written code. But it doesn’t have to be that way.

And how to code like a clean coder? There are some principles I’m going to list that will help you and convince you to read this awesome piece.

1. Write meaningful names

Variables, classes, functions and methods must be named semantically. Don’t abbreviate names and name your code with meaning.

// bad 🙁
def dvd(v1, v2)
  return v1 / v2
end
res = dvd(10, 2)

// good 🙂
def divide(dividend, divisor)
  return dividend / divisor
end
quotient = divide(10, 2)

By giving more semantics to your code, you’ll be able to understand it in your next editing session.

Apart from meaningful names, a clean coder will also write searchable names, such as:

// bad 🙁
wait(foo, 86400000)

// good 🙂
MILLISECONDS_IN_A_DAY = 86400000;
wait(foo, MILLISECONDS_IN_A_DAY)

2. Don’t add unneeded context

If you are writing a method or field inside a class, for instance, you don’t need to refer the class context in the method/field name.

# bad 🙁
class Person
  property :person_name
end

# good 🙂
class Person
  property :name
end

3. Let your code speak

Good code over comments. That’s a rule. Comments are necessary, but if your code explains itself, you won’t need comments.

Comments can be evil.

# always returns true
def available?
  return false
end

Commented code can be hard to read.

In a quick code review, a commented code line can mess everything up.

employee.work
boss.promote(employee)
# employee.party
employee.work

Why should you read Clean Code? Programmers spend more time reading code than writing. That’s a fact. To read code can be confusing if the code base is bad written, obsolete or legacy. To reduce the confusion and time lost, there are some companies paying their employees to read this book.

By teaching how to write software well, Clean Code is creating a huge group of programmers that care about what they are writing and who’s going to read it: the clean coders.