Code Quality Essentials

Good code quality isn’t about impressing your peers with clever tricks. It’s about writing code that works now, still works six months from now, and doesn’t make the next person (probably you) want to quit.

What This Is

Code quality is how well your code does its job while being maintainable, understandable, and changeable. High-quality code:

• Works correctly - Does what it’s supposed to do
• Reads clearly - Another developer (or future you) understands it quickly
• Changes safely - You can modify it without breaking everything
• Fails visibly - When something goes wrong, you know immediately

Quality isn’t about writing perfect code. It’s about writing code that doesn’t fight you when requirements change, bugs appear, or someone needs to understand what you built.

Minimum Viable Understanding

If you only remember three things about code quality:

1. Name things clearly

Your variable and function names should explain what they do. If you need a comment to explain what x means, rename x.

# Bad
def calc(d, r):
    return d * (1 + r/100)

# Good
def calculate_price_with_tax(subtotal, tax_rate_percentage):
    return subtotal * (1 + tax_rate_percentage/100)

2. Each function does one thing

If you can’t describe what a function does in a simple sentence without using “and”, it probably does too much.

// Bad - does three different things
function processUserData(user) {
    validateEmail(user.email);
    user.lastLogin = new Date();
    sendWelcomeEmail(user);
    return user;
}

// Good - each function has one job
function validateUserEmail(user) {
    return validateEmail(user.email);
}

function updateLastLogin(user) {
    user.lastLogin = new Date();
    return user;
}

function sendUserWelcome(user) {
    sendWelcomeEmail(user);
}

3. Don’t copy-paste code

If you’re copying code to use in multiple places, you’re creating multiple places to fix when bugs appear. Extract it into a reusable function.

// Bad - duplicated logic
public double calculateEmployeeBonus(Employee emp) {
    return emp.getSalary() * 0.1 * emp.getPerformanceRating();
}

public double calculateContractorBonus(Contractor con) {
    return con.getHourlyRate() * 0.1 * con.getPerformanceRating();
}

// Good - shared logic
private double applyBonusMultiplier(double baseAmount, double rating) {
    return baseAmount * 0.1 * rating;
}

public double calculateEmployeeBonus(Employee emp) {
    return applyBonusMultiplier(emp.getSalary(), emp.getPerformanceRating());
}

public double calculateContractorBonus(Contractor con) {
    return applyBonusMultiplier(con.getHourlyRate(), con.getPerformanceRating());
}

That’s it. Master these three and you’re ahead of half the codebases out there.

Real Red Flags

These are signs your code quality needs immediate attention:

❌ Magic Numbers

# What does 86400 mean?
if elapsed_seconds > 86400:
    send_reminder()

✅ Named Constants

SECONDS_PER_DAY = 86400

if elapsed_seconds > SECONDS_PER_DAY:
    send_reminder()

❌ God Classes

A single class or module that does everything - user management, database access, email sending, logging, authorization. If your class has 2000 lines and handles 15 different concerns, it’s unmaintainable.

✅ Focused Modules

Each module handles one area of responsibility. Your user authentication module shouldn’t also be sending marketing emails.

❌ Cryptic Variable Names

const d = new Date();
const x = u.filter(i => i.a);

✅ Descriptive Names

const currentDate = new Date();
const activeUsers = users.filter(user => user.isActive);

❌ Functions That Do Too Much

// This function validates, saves, emails, logs, and updates cache
func ProcessOrder(order Order) error {
    // 150 lines of mixed concerns
}

✅ Single-Purpose Functions

func ValidateOrder(order Order) error { }
func SaveOrder(order Order) error { }
func NotifyCustomer(order Order) error { }
func UpdateOrderCache(order Order) error { }

❌ Copy-Paste Code Blocks

The same 20 lines of code appear in five different places. You find a bug in one place and forget to fix it in the other four.

✅ Extracted Functions

The logic exists once. You fix it once. Everyone benefits.

Good vs Bad Examples

Example 1: Processing User Input

Bad:

def process(d):
    if d["t"] == "a":
        x = d["v"] * 1.1
        if x > 100:
            return {"s": "fail", "m": "too high"}
        else:
            db.save(x)
            return {"s": "ok"}
    elif d["t"] == "b":
        x = d["v"] * 0.9
        if x > 100:
            return {"s": "fail", "m": "too high"}
        else:
            db.save(x)
            return {"s": "ok"}

What’s wrong:

• Cryptic variable names
• Magic numbers (1.1, 0.9, 100)
• Duplicated validation and save logic
• Unclear what the function does

Good:

MAX_ALLOWED_VALUE = 100
TYPE_A_MULTIPLIER = 1.1
TYPE_B_MULTIPLIER = 0.9

def process_transaction(transaction_data):
    transaction_type = transaction_data["type"]
    value = transaction_data["value"]

    adjusted_value = calculate_adjusted_value(value, transaction_type)

    if not is_within_limit(adjusted_value):
        return create_error_response("Value exceeds maximum allowed")

    save_transaction(adjusted_value)
    return create_success_response()

def calculate_adjusted_value(value, transaction_type):
    multipliers = {
        "type_a": TYPE_A_MULTIPLIER,
        "type_b": TYPE_B_MULTIPLIER
    }
    return value * multipliers.get(transaction_type, 1.0)

def is_within_limit(value):
    return value <= MAX_ALLOWED_VALUE

What’s better:

• Clear names explain intent
• Named constants instead of magic numbers
• Single responsibility per function
• Easy to test each piece independently
• Easy to add new transaction types

Example 2: Error Handling

Bad:

function getData() {
    try {
        const response = fetch('/api/data');
        const data = response.json();
        const processed = data.map(x => x.value * 2);
        const filtered = processed.filter(x => x > 10);
        saveToDatabase(filtered);
        updateCache(filtered);
        logSuccess();
        return filtered;
    } catch (e) {
        console.log('error');
        return null;
    }
}

What’s wrong:

• One giant function doing everything
• Error handling loses all context
• No way to know which step failed
• Can’t test individual steps

Good:

function getData() {
    const rawData = fetchDataFromApi();
    const processedData = processData(rawData);
    const validData = filterValidData(processedData);
    persistData(validData);
    return validData;
}

function fetchDataFromApi() {
    try {
        const response = fetch('/api/data');
        return response.json();
    } catch (error) {
        throw new DataFetchError(`Failed to fetch data: ${error.message}`);
    }
}

function processData(data) {
    return data.map(item => item.value * 2);
}

function filterValidData(data) {
    const threshold = 10;
    return data.filter(value => value > threshold);
}

function persistData(data) {
    saveToDatabase(data);
    updateCache(data);
    logSuccess('Data persisted successfully');
}

What’s better:

• Each function has a clear purpose
• Errors tell you exactly what failed
• Each step is testable independently
• Easy to modify one step without affecting others

Quick Validation Test

Run your code through this checklist before you call it done:

1. Can someone else read it? If you need to explain it, the code should be clearer
2. Are names descriptive? No single letters, abbreviations, or cryptic shortcuts
3. Any magic numbers? Replace them with named constants
4. Functions under 50 lines? If not, can you break them up?
5. Copied code blocks? Extract them into reusable functions
6. One job per function? Can you describe it in one sentence without “and”?
7. Any commented-out code? Delete it (it’s in version control)
8. Obvious what could go wrong? Error handling shows what failed and why

If you answered no to any of these, you have specific work to do.

One-Sentence Maxim

Write code for the developer who maintains it at 3am during an outage - that developer is probably you.

What’s Next

This is the bare minimum. If you want to ship code that doesn’t embarrass you three months from now, these principles are non-negotiable.

For deeper understanding of how to apply these principles systematically, see Mid-Depth: Code Quality in Practice. For advanced considerations in large codebases and team environments, see Deep Water: Enterprise Code Quality.