Developers spend far more time reading code than writing it. That’s because you’re rarely writing code from scratch — you’re usually maintaining or extending an existing codebase.
Before making any changes, you need to understand the code first. And when the code isn’t readable, that understanding takes longer, which slows you down.
This is why readability matters.
"readableCode" == "fasterProgress" 🚀“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
Because most development time is spent reading and understanding code, prioritising readability helps you and your team move faster. This makes focusing on clean and clear code far more important than premature attempts to optimise performance.
Readability over performance
Modern computers and programming languages are powerful enough that, in most cases, performance optimisation shouldn’t be your primary focus. You should only worry about performance when it actually 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
Trying to optimise too early introduces unnecessary complexity and attempts to solve problems that don’t exist yet. In scenarios where performance is critical, it’s a good idea to include proper documentation 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 was doing?
It’s easy to assume your future self will be able to read your code effortlessly since you wrote it. But the truth is, if the code isn’t readable, you’ll likely forget the context and struggle to understand it. Now, imagine reading someone else’s code.
That’s 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.
• Keep it simple by following the KISS principle
• Use meaningful names to name things
• Keep the codebase consistent
Treat these tips as guidelines rather than strict rules.
1. KISS – Keep it simple, stupid! 🎯
Simple is good.
Aim to write simple code because it reduces complexity and is easier to understand. Avoid clever tricks that can confuse — clarity beats cleverness every time.
“Simplicity is the ultimate sophistication.”
— Leonardo da Vinci
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 developers 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 deep nesting 🌀
Avoid deeply nested conditionals as they add unnecessary complexity. Instead, flatten your logic to keep the main path clear and easy to follow.
❌ 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 of parameters 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’re 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 put extra effort into writing readable code. When code is readable, it’s easy to understand and modify, making it flexible and maintainable.
In most cases, modern computers are powerful enough that performance is rarely an issue. When performance does become critical, it’s important to document any optimisations to explain the trade-offs involved. By focusing on readability first, we ensure our software remains adaptable and easy to evolve over time.
What strategies do you use to write readable code?