Clean Code Principles

Clean Code Principles

Writing code that works is only half the battle. Writing code that others (and your future self) can understand is the real challenge. Here are core principles for writing clean, maintainable code.

Meaningful Names

Variable, function, and class names should reveal their purpose. Avoid single-letter names except in trivial loops.

# Bad
def calc(d):
    return d * 0.1

# Good
def calculate_discount(price):
    return price * 0.1

Small Functions

Functions should do one thing, do it well, and do it only. A good rule of thumb: if a function can't fit on a screen without scrolling, it's probably too long.

# Bad — does too much
def process_user(data):
    validate(data)
    hash_password(data["password"])
    save_to_db(data)
    send_welcome_email(data)
    log_activity(data)

# Good — each function has a single responsibility
def create_user(user_data):
    validated = validate_user(user_data)
    hashed = hash_password(validated["password"])
    saved = save_to_database(validated, hashed)
    send_welcome_email(saved)
    log_activity(saved)
    return saved

Avoid Commented-Out Code

Commented-out code is dead code. It goes stale, becomes misleading, and clutters your files. If you need to preserve it, use version control.

Consistent Formatting

Consistent formatting is more important than any particular style choice. Use linters and formatters (Prettier, Black, ESLint) to automate this. Your team should agree on one style and stick to it.

DRY — Don't Repeat Yourself

When you see the same logic duplicated across multiple places, extract it into a reusable function or module. Duplication is the root of many maintenance headaches.

# Before: duplicated validation logic
def create_user(data):
    if not data.get("email"):
        raise ValueError("Email is required")
    if not data.get("name"):
        raise ValueError("Name is required")

def update_user(data):
    if not data.get("email"):
        raise ValueError("Email is required")
    if not data.get("name"):
        raise ValueError("Name is required")

# After: DRY
def validate_user_data(data):
    required_fields = ["email", "name"]
    for field in required_fields:
        if not data.get(field):
            raise ValueError(f"{field} is required")

Conclusion

Clean code isn't about following arbitrary rules — it's about respecting the people who will read your code after you. Write for humans first, machines second. Your future self will thank you.