✨ Writing Clean, Understandable, and Maintainable Code

Writing clean, readable, and maintainable code is one of the most important skills every developer must master. Your code is not just a set of instructions for the computer—it's a form of communication with your future self and your teammates. Good code saves time, reduces bugs, and makes collaboration easier.

In this post, we'll explore essential principles to help you write cleaner code. Most of the examples and guidelines come from Clean Code by Robert C. Martin, a classic book that every developer should read.

---

🔤 Meaningful Naming Matters

One of the simplest yet most impactful changes you can make to your code is using clear, descriptive names. Names should describe the purpose of the variable, function, or class without the need for extra comments.

“A name should tell you why it exists, what it does, and how it is used.” – Clean Code

❌ Bad:

var d; // elapsed time in days

### ✅ Good:

var elapsedTimeInDays;
var daysSinceCreation;
var daysUntilDeadline;

The good examples explain the purpose and unit of measurement clearly. You don't need a comment to understand them.

---

🛑 Avoid Misleading or Redundant Names

🔸 Avoid Disinformation

Choose names that reflect their actual type or behavior. For example, avoid using accountList if the variable is an array or another type—not a list in the technical sense.

❌ Bad:

var accountList = [];

### ✅ Good:

var accounts = [];

---

🔸 Avoid Noise Words

Words like data, info, variable, or object often add no value.

❌ Bad:

class UserInfo {}
class BookData {}

### ✅ Good:

class User {}
class Book {}

Names should be as simple as possible without losing meaning.

---

🔸 Use Pronounceable and Searchable Names

If a name is hard to say or find in code, it’s a red flag.

❌ Bad:

const yyyymmdstr = moment().format("YYYY/MM/DD");

### ✅ Good:

const currentDate = moment().format("YYYY/MM/DD");

Magic numbers and one-letter names make your code cryptic. Use named constants instead.

❌ Bad:

if (student.classes.length < 7) {
// do something
}

### ✅ Good:

const MAX_CLASSES_PER_STUDENT = 7;

if (student.classes.length < MAX_CLASSES_PER_STUDENT) {
    // do something
}

---

🧱 Be Consistent in Terminology

Use the same word for the same concept throughout your codebase. Don’t mix fetch, get, and retrieve to describe the same behavior—it confuses other developers (and your future self).

---

🧠 How to Write Better Functions

✂️ Keep Them Small

Functions should be as short as possible. Ideally, they should do one thing only—and do it well.

“Functions should do one thing. They should do it well. They should do it only.” – Clean Code

🧪 Test for Single Responsibility

If you can extract another function with a meaningful name, your original function is probably doing too much and should be split.

---

✅ Encapsulate Complex Conditions

Instead of writing complex conditions inline, extract them into well-named functions. This makes your code easier to read and understand.

❌ Without Encapsulation:

if (column <= NUM_COLUMNS && column >= 1 && numberOfItemsInColumn[column - 1] < NUM_ROWS && getWinner() == Chip.NONE) {
    // insert chip
}

✅ With Encapsulation:

if (isValidInsertion(column)) {
    insertChip(column);
}

This improves both readability and maintainability.

---

🚫 Avoid Too Many Arguments

Functions should ideally take no more than two arguments. The more parameters a function has, the harder it is to read, understand, and test.

🚫 Avoid Flag Arguments

Flag arguments (e.g., isPremium) make your function do more than one thing. Instead, split the behavior into two separate functions.

❌ Bad:

public Booking book(Customer customer, boolean isPremium) {
    if (isPremium) {
        // premium logic
    } else {
        // regular logic
    }
}

✅ Good:

public Booking bookPremium(Customer customer) { ... }
public Booking bookRegular(Customer customer) { ... }

---

🔍 Eliminate Side Effects

Functions should do what their name says—and nothing more. Avoid hidden side effects like modifying global variables or starting sessions silently.

❌ Bad:

public boolean checkPassword(String userName, String password) {
    ...
    if (isValid) {
        Session.initialize(); // side effect!
        return true;
    }
    return false;
}

This function should only validate the password, not change application state.

---

🧼 Don’t Repeat Yourself (DRY)

Duplication is a major source of bugs. When logic is repeated in multiple places, changes become risky and error-prone. Extract repeated code into reusable functions or modules to improve maintainability.

---

📌 Final Thoughts

Writing clean code is not about following rigid rules, but about improving communication and reducing complexity. These principles might feel unfamiliar at first, but applying them consistently will drastically improve the quality of your codebase.

It’s not just about making your life easier—your team, future maintainers, and your future self will thank you.

Clean code always looks like it was written by someone who cares. – Michael Feathers