Developers spend 10x more time reading code than writing it. Writing code from scratch is rare; you’re often maintaining or extending an existing codebase. This requires you to understand the codebase before making any changes. And when the code isn’t very readable, it slows you down because it’s harder to understand.
This is why readability matters.
"readableCode" == "fasterProgress" 🚀“Indeed, the ratio of time spent reading versus writing is well over 10 to 1. We are constantly reading old code as part of the effort to write new code. …[Therefore,] making it easy to read makes it easier to write.”
— Robert C. Martin, Clean Code: A Handbook of Agile Software Craftmanship
Readability over performance
Modern computers and programming languages are powerful enough that, in most cases, performance optimisation doesn’t need to be your primary focus. You should only worry about performance when it becomes an issue.
“ Premature optimisation is the root of all evil (or at least most of it) in programming”
— Donald Knuth, The Art of Computer Programming
Premature optimisation introduces unnecessary complexity and tries to solve a problem that isn’t there. In scenarios where performance is critical, it’s a good idea to put proper documentation in place to explain the code and the trade offs made during the optimisation process.
Be kind to your future self 🤝
Ever looked at your own code from six months ago and had no idea what it’s doing?
It’s easy to assume your future self will be able to read your code effortlessly since they wrote it. But the truth is, if the code isn’t readable, they’ll struggle to understand it because they’ll likely forget the context behind it. Now, imagine reading someone else’s code.
This is why, when writing code, you should think about future developers—including your future self. Trust me, your future self will thank you. 🙏
“Any fool can write code that a computer can understand. Good programmers write code that humans can understand.”
— Martin Fowler, Refactoring: Improving the Design of Existing Code
Writing readable code ✍️
Writing readable code is more of an art than a hard science, making it difficult to create a concrete formula to follow. However, the following principles are generally recommended to help write readable code.
• KISS
• Meaningful names
• Consistency
Treat these tips as guidelines rather than strict rules.
1. KISS – Keep it simple, stupid! 🎯
Simple is good.
i. Avoid negative conditionals
❌ Bad code:
if (!isInValid) {
// do something
}✅ Good code:
if (isValid) {
// do something
}ii. Return early ⏭️
Return as soon as possible. This allows a developer to read code only until the point it’s needed.
❌ Bad code:
if (isValid) {
if (isSecure) {
// main logic here
} else {
// throw exception
}
} else {
// do something
}✅ Good code:
if (!isValid) {
// do something
// return
}
if (!isSecure) {
// throw exception
}
// main logic hereiii. Avoid else and nesting 🌀
Using else statements and nesting if statements increase complexity.
❌ Bad code:
if (isValid) {
if (isSecure) {
// main logic here
} else {
if (isImportant) {
// throw exception
} else {
// do something
}
}
}✅ Good code:
if (!isValid) {
// return
}
if (!isSecure && isImportant) {
// do something
// return
}
// main logic hereiv. Decompose long functions ✂️
If a function is too long, break it down by extracting related logic into smaller functions. The original function can then call these new functions.
❌ Bad code:
function createSomething() {
// validate input
// save to database
// log activity
}✅ Good code:
function createSomething() {
validateInput()
saveToDatabase()
logActivity()
}
function validateInput() {
}
function saveToDatabase() {
}
function logActivity() {
}v. Limit function parameters
If a function has too many parameters, limit the number by grouping related parameters into an object.
❌ Bad code:
function createUser(name, age, gender, email, address, phone) {
// logic here
}✅ Good code:
function createUser(user) {
// logic here
}
user = {
name: "John",
age: 21,
gender: "male"
email: "john@example.com",
address: "123 street",
phone: "123-456-789"
}
createUser(user)vi. Break down complex conditions
When the conditions are too complex, break them down.
❌ Bad code:
if (age >= 18 && age <= 65 && role == "employee" && isActive && !isOnHoliday) {
// do something
}✅ Good code:
isEligibleAge = age >= 18 && age <=65
isEligibleEmployee = role == "employee" && isActive && !isOnHoliday
if (isEligibleAge && isEligibleEmployee) {
// do something
}vii. Avoid complex ternary expressions
Avoid complex ternary expressions as they are hard to read.
❌ Bad code:
result = (age >= 18 && age <= 65)
? (role === "employee"
? (isActive
? "active employee"
: "inactive employee")
: "not an employee")
: "not eligible";✅ Good code:
isEligibleAge = age >= 18 && age <=65
isEmployee = role == "employee"
if (!isEligibleAge) {
result = "not eligible"
// return
}
if (!isEmployee) {
result = "not an employee"
// return
}
result = isActive ? "active employee" : "inactive employee"2. Meaningful names 💡
There are only two hard things in computer science: cache invalidation and naming things.
— Phil Karlton
Naming things in programming is a critical skill that greatly impacts readability. Spending extra time upfront to come up with a good name always pays off in the future.
i. Pronounceable names 🗣️
Pronounceable names are easier to read, understand and facilitate better communication with other developers.
❌ Bad names:
yyyymmdString = "1990/01/01"
n = 100
calcTotAmt()✅ Good names:
currentDate = "1990/01/01"
numberOfUsers = 100
calculateTotalAmount()ii. Descriptive names
Names should self-describe what the “thing” does or represents. The following is a good rule of thumb for naming things.
a. Nouns for variables and classes
user = new User()
favouriteColour = "Blue"
validator = new InputValidator()b. Verb + noun for functions and methods
sendEmail()
createUser()
calculateSalary() c. is or has prefix for booleans
isActive = true
isLoggedin = false
hasPermission = falseiii. Avoid magic numbers
Magic numbers are literal values in your code without a clear explanation of their meaning. This makes the code vague and difficult to understand.
❌ Bad code:
if (age > 18) {
discount = total * 0.1
}✅ Good code:
LEGAL_AGE = 18
DISCOUNT_RATE = 0.1
if (age > LEGAL_AGE) {
discount = total * DISCOUNT_RATE
}3. Consistency
Consistency in a codebase makes it easier to read and understand because the code feels cohesive and reduces unnecessary context switching.
i. Formatting ✏️
Use linters or code formatting tools to help achieve consistent formatting for:
a. Indentation
b. Braces placement
c. Blank lines
d. Line length – ensure lines fit on the screen
e. Spacing – e.g. a + b instead of a+b
ii. Standards 📜
Follow a consistent standard across your codebase for:
a. Names 🏷️
b. Comment style 💬
c. Error handling 🚨
d. Testing 🧪
e. Logging
iii. Code organisation 🗂️
Ensure the following aspects of code organisation are consistent:
a. Folder and file names 📁
b. Folder and file structure 📂 – group related components logically
c. Documentation 📖 – create a README that includes:
• 📝 A high level overview of the project
• 🌟 Highlight key modules / components
• ⚙️ Instructions to run tests and the program
Conclusion
Since reading code is a fundamental part of software engineering, it’s in our best interest to focus on writing high-quality readable code. When code is readable, it’s easy to read, understand and modify, making it flexible and maintainable.
In most cases, modern computers are powerful enough that performance never becomes an issue. By focusing on readability over performance, we can ensure our software remains adaptable and easy to modify if needed.
What strategies do you use to write readable code?