Article 4: Clean Code Principles

Introduction

Clean code is code that's easy to read, understand, and modify. Through years of maintaining codebases—some clean, some not—I've learned that the time saved by writing "quick and dirty" code is always repaid with interest during maintenance.

This article covers the fundamental principles of writing clean code, including naming conventions, function design, and introductory design patterns that make code self-documenting and maintainable.

What Makes Code Clean?

Clean code:

• Reads like prose - Intent is immediately clear

• Does one thing well - Single responsibility

• Has no surprises - Behaves as expected

• Is easily testable - Clear inputs and outputs

• Minimizes dependencies - Low coupling

Meaningful Names

Variables

# Bad: Cryptic or misleading names
d = 86400  # What is this?
lst = []   # List of what?
temp = get_user()  # Not temporary!

# Good: Intention-revealing names
seconds_per_day = 86400
active_users: list[User] = []
current_user = get_user()

Naming Conventions

Type	Convention	Example
Variables	snake_case	user_count, is_active
Constants	UPPER_SNAKE_CASE	MAX_RETRIES, API_URL
Functions	snake_case (verb)	get_user(), calculate_total()
Classes	PascalCase (noun)	UserAccount, TaskManager
Modules	snake_case	user_service.py, data_models.py
Private	leading underscore	_internal_method(), _cache

Functions

# Bad: Vague or misleading function names
def process(data):  # Process how?
    pass

def handle_stuff():  # What stuff?
    pass

def get_data():  # Get what data? From where?
    pass

# Good: Specific, action-oriented names
def validate_email(email: str) -> bool:
    pass

def calculate_order_total(order: Order) -> Decimal:
    pass

def fetch_user_by_id(user_id: int) -> Optional[User]:
    pass

Classes

# Bad: Unclear purpose
class Manager:  # Manager of what?
    pass

class DataHandler:  # Too generic
    pass

# Good: Clear domain concepts
class TaskRepository:
    """Manages persistence of Task entities."""
    pass

class EmailValidator:
    """Validates email address format and domain."""
    pass

class OrderCalculator:
    """Calculates totals, taxes, and discounts for orders."""
    pass

Boolean Naming

# Bad: Unclear boolean meaning
flag = True
status = False
check = user.active

# Good: Question-like boolean names
is_active = True
has_permission = False
should_retry = attempt < max_attempts
can_edit = user.is_admin or user.id == document.author_id

Function Design

Small Functions

Functions should do one thing and do it well:

# Bad: Function doing too many things
def process_order(order: Order) -> None:
    # Validate
    if not order.items:
        raise ValueError("Order has no items")
    for item in order.items:
        if item.quantity <= 0:
            raise ValueError(f"Invalid quantity for {item.name}")
    
    # Calculate totals
    subtotal = sum(item.price * item.quantity for item in order.items)
    tax = subtotal * Decimal("0.08")
    total = subtotal + tax
    order.total = total
    
    # Save to database
    db.session.add(order)
    db.session.commit()
    
    # Send confirmation email
    email_body = f"Your order total is ${total}"
    send_email(order.customer.email, "Order Confirmation", email_body)


# Good: Small, focused functions
def validate_order(order: Order) -> None:
    """Validate order has items with valid quantities."""
    if not order.items:
        raise ValueError("Order has no items")
    
    for item in order.items:
        if item.quantity <= 0:
            raise ValueError(f"Invalid quantity for {item.name}")


def calculate_order_total(order: Order) -> Decimal:
    """Calculate order total including tax."""
    subtotal = sum(item.price * item.quantity for item in order.items)
    tax = subtotal * Decimal("0.08")
    return subtotal + tax


def save_order(order: Order) -> None:
    """Persist order to database."""
    db.session.add(order)
    db.session.commit()


def send_order_confirmation(order: Order) -> None:
    """Send confirmation email to customer."""
    email_body = f"Your order total is ${order.total}"
    send_email(order.customer.email, "Order Confirmation", email_body)


def process_order(order: Order) -> None:
    """Process an order: validate, calculate, save, and notify."""
    validate_order(order)
    order.total = calculate_order_total(order)
    save_order(order)
    send_order_confirmation(order)

Function Arguments

# Bad: Too many arguments
def create_user(
    first_name: str,
    last_name: str,
    email: str,
    phone: str,
    address: str,
    city: str,
    country: str,
    postal_code: str,
    is_admin: bool,
    department: str,
) -> User:
    pass


# Good: Use objects to group related data
@dataclass
class UserProfile:
    first_name: str
    last_name: str
    email: str
    phone: str


@dataclass
class Address:
    street: str
    city: str
    country: str
    postal_code: str


def create_user(
    profile: UserProfile,
    address: Address,
    is_admin: bool = False,
    department: Optional[str] = None,
) -> User:
    pass

Avoid Flag Arguments

# Bad: Boolean flag changes function behavior
def get_users(include_inactive: bool = False) -> list[User]:
    if include_inactive:
        return db.query(User).all()
    return db.query(User).filter(User.is_active == True).all()


# Good: Separate functions with clear intent
def get_active_users() -> list[User]:
    """Get all active users."""
    return db.query(User).filter(User.is_active == True).all()


def get_all_users() -> list[User]:
    """Get all users including inactive ones."""
    return db.query(User).all()

Command-Query Separation

Functions should either do something (command) or return something (query), not both:

# Bad: Does both - confusing side effects
def set_and_get_username(user: User, name: str) -> str:
    user.name = name  # Command: changes state
    db.commit()
    return user.name  # Query: returns value


# Good: Separate commands from queries
def set_username(user: User, name: str) -> None:
    """Update user's name."""
    user.name = name
    db.commit()


def get_username(user: User) -> str:
    """Get user's name."""
    return user.name

Code Organization

Vertical Formatting

# Good: Related code grouped together, separated by blank lines

class OrderService:
    """Service for managing orders."""

    def __init__(self, repository: OrderRepository) -> None:
        self._repository = repository

    # Public interface
    def create_order(self, customer: Customer, items: list[Item]) -> Order:
        """Create a new order for a customer."""
        order = Order(customer=customer, items=items)
        self._validate_order(order)
        self._calculate_totals(order)
        return self._repository.save(order)

    def get_order(self, order_id: int) -> Optional[Order]:
        """Retrieve an order by ID."""
        return self._repository.find_by_id(order_id)

    # Private implementation details
    def _validate_order(self, order: Order) -> None:
        """Validate order before processing."""
        if not order.items:
            raise ValueError("Order must have items")

    def _calculate_totals(self, order: Order) -> None:
        """Calculate order subtotal, tax, and total."""
        order.subtotal = sum(item.total for item in order.items)
        order.tax = order.subtotal * Decimal("0.08")
        order.total = order.subtotal + order.tax

Module Organization

# Good module structure
"""
User management module.

This module provides functionality for user authentication and management.
"""

# Standard library imports
from dataclasses import dataclass
from datetime import datetime
from typing import Optional

# Third-party imports
from passlib.hash import bcrypt

# Local imports
from .database import db
from .exceptions import AuthenticationError

# Constants
MAX_LOGIN_ATTEMPTS = 5
SESSION_TIMEOUT_HOURS = 24

# Data classes / Models
@dataclass
class User:
    id: int
    email: str
    password_hash: str
    created_at: datetime


# Public functions (API)
def authenticate(email: str, password: str) -> User:
    """Authenticate user with email and password."""
    ...


def create_user(email: str, password: str) -> User:
    """Create a new user account."""
    ...


# Private helpers
def _hash_password(password: str) -> str:
    """Hash password using bcrypt."""
    ...

Comments and Documentation

When to Comment

# Bad: Comments that state the obvious
i = i + 1  # Increment i

# Get user from database
user = db.query(User).filter(User.id == user_id).first()


# Good: Comments that explain WHY, not WHAT

# Retry with exponential backoff to handle transient network failures
for attempt in range(max_retries):
    try:
        return api_client.fetch(url)
    except NetworkError:
        wait_time = 2 ** attempt
        time.sleep(wait_time)

# Using raw SQL here because the ORM doesn't support this specific
# window function syntax needed for the running total calculation
result = db.execute("""
    SELECT id, amount,
           SUM(amount) OVER (ORDER BY created_at) as running_total
    FROM transactions
""")

Self-Documenting Code

# Bad: Needs comment to explain
# Check if user can edit the document
if user.role == "admin" or (user.id == doc.author_id and not doc.locked):
    ...

# Good: Self-documenting with extracted method
def can_edit_document(user: User, document: Document) -> bool:
    """Check if user has permission to edit the document."""
    is_admin = user.role == "admin"
    is_author = user.id == document.author_id
    is_unlocked = not document.locked
    
    return is_admin or (is_author and is_unlocked)

if can_edit_document(user, doc):
    ...

Docstrings

def fetch_user_orders(
    user_id: int,
    status: Optional[OrderStatus] = None,
    limit: int = 100,
) -> list[Order]:
    """
    Fetch orders for a specific user.

    Retrieves orders from the database, optionally filtered by status.
    Results are ordered by creation date, newest first.

    Args:
        user_id: The ID of the user whose orders to fetch.
        status: Optional filter for order status. If None, returns all orders.
        limit: Maximum number of orders to return. Defaults to 100.

    Returns:
        List of Order objects, ordered by creation date descending.

    Raises:
        UserNotFoundError: If no user exists with the given ID.
        DatabaseError: If there's a problem connecting to the database.

    Example:
        >>> orders = fetch_user_orders(123, status=OrderStatus.PENDING)
        >>> len(orders)
        5
    """
    ...

Introduction to Design Patterns

Design patterns are reusable solutions to common problems. Here are foundational patterns you'll use frequently.

Factory Pattern

Creates objects without exposing creation logic:

from abc import ABC, abstractmethod
from dataclasses import dataclass


# Abstract base class
class Notification(ABC):
    @abstractmethod
    def send(self, message: str) -> None:
        pass


# Concrete implementations
class EmailNotification(Notification):
    def __init__(self, email: str) -> None:
        self.email = email

    def send(self, message: str) -> None:
        print(f"Sending email to {self.email}: {message}")


class SMSNotification(Notification):
    def __init__(self, phone: str) -> None:
        self.phone = phone

    def send(self, message: str) -> None:
        print(f"Sending SMS to {self.phone}: {message}")


class PushNotification(Notification):
    def __init__(self, device_token: str) -> None:
        self.device_token = device_token

    def send(self, message: str) -> None:
        print(f"Sending push to {self.device_token}: {message}")


# Factory
class NotificationFactory:
    """Factory for creating notification instances."""

    @staticmethod
    def create(
        notification_type: str,
        destination: str,
    ) -> Notification:
        """Create a notification based on type."""
        factories = {
            "email": EmailNotification,
            "sms": SMSNotification,
            "push": PushNotification,
        }

        factory = factories.get(notification_type)
        if not factory:
            raise ValueError(f"Unknown notification type: {notification_type}")

        return factory(destination)


# Usage
notification = NotificationFactory.create("email", "[email protected]")
notification.send("Hello!")

Strategy Pattern

Enables selecting algorithms at runtime:

from abc import ABC, abstractmethod
from decimal import Decimal


class PricingStrategy(ABC):
    """Base class for pricing strategies."""

    @abstractmethod
    def calculate_price(self, base_price: Decimal, quantity: int) -> Decimal:
        pass


class RegularPricing(PricingStrategy):
    """Standard pricing with no discounts."""

    def calculate_price(self, base_price: Decimal, quantity: int) -> Decimal:
        return base_price * quantity


class BulkPricing(PricingStrategy):
    """10% discount for orders over 10 items."""

    def calculate_price(self, base_price: Decimal, quantity: int) -> Decimal:
        total = base_price * quantity
        if quantity > 10:
            total *= Decimal("0.90")  # 10% discount
        return total


class PremiumPricing(PricingStrategy):
    """20% discount for premium customers."""

    def calculate_price(self, base_price: Decimal, quantity: int) -> Decimal:
        return base_price * quantity * Decimal("0.80")


# Context class that uses a strategy
class ShoppingCart:
    def __init__(self, pricing_strategy: PricingStrategy) -> None:
        self._pricing = pricing_strategy
        self._items: list[tuple[str, Decimal, int]] = []

    def add_item(self, name: str, price: Decimal, quantity: int) -> None:
        self._items.append((name, price, quantity))

    def calculate_total(self) -> Decimal:
        return sum(
            self._pricing.calculate_price(price, qty)
            for _, price, qty in self._items
        )


# Usage
cart = ShoppingCart(BulkPricing())
cart.add_item("Widget", Decimal("10.00"), 15)
total = cart.calculate_total()  # 135.00 (10% off)

Repository Pattern

Abstracts data access logic:

from abc import ABC, abstractmethod
from dataclasses import dataclass
from typing import Optional


@dataclass
class Task:
    id: Optional[int]
    title: str
    completed: bool = False


class TaskRepository(ABC):
    """Abstract repository for Task entities."""

    @abstractmethod
    def save(self, task: Task) -> Task:
        """Save a task and return it with ID populated."""
        pass

    @abstractmethod
    def find_by_id(self, task_id: int) -> Optional[Task]:
        """Find a task by ID."""
        pass

    @abstractmethod
    def find_all(self) -> list[Task]:
        """Get all tasks."""
        pass

    @abstractmethod
    def delete(self, task_id: int) -> bool:
        """Delete a task, return True if successful."""
        pass


class InMemoryTaskRepository(TaskRepository):
    """In-memory implementation for testing."""

    def __init__(self) -> None:
        self._tasks: dict[int, Task] = {}
        self._next_id = 1

    def save(self, task: Task) -> Task:
        if task.id is None:
            task.id = self._next_id
            self._next_id += 1
        self._tasks[task.id] = task
        return task

    def find_by_id(self, task_id: int) -> Optional[Task]:
        return self._tasks.get(task_id)

    def find_all(self) -> list[Task]:
        return list(self._tasks.values())

    def delete(self, task_id: int) -> bool:
        if task_id in self._tasks:
            del self._tasks[task_id]
            return True
        return False


class SQLTaskRepository(TaskRepository):
    """SQL database implementation for production."""

    def __init__(self, session) -> None:
        self._session = session

    def save(self, task: Task) -> Task:
        self._session.add(task)
        self._session.commit()
        return task

    # ... other methods

Code Smells and Refactoring

Long Method

# Smell: Method too long, doing too many things
def generate_report(orders: list[Order]) -> str:
    # 50+ lines of code doing validation, calculation,
    # formatting, and file writing
    pass


# Refactored: Extract methods
def generate_report(orders: list[Order]) -> str:
    validated = _validate_orders(orders)
    statistics = _calculate_statistics(validated)
    formatted = _format_report(statistics)
    return formatted

Duplicated Code

# Smell: Same logic repeated
def get_active_users() -> list[User]:
    users = db.query(User).filter(User.is_active == True).all()
    return [u for u in users if u.email_verified]


def get_admin_users() -> list[User]:
    users = db.query(User).filter(User.is_admin == True).all()
    return [u for u in users if u.email_verified]


# Refactored: Extract common logic
def _get_verified_users(query) -> list[User]:
    users = query.all()
    return [u for u in users if u.email_verified]


def get_active_users() -> list[User]:
    query = db.query(User).filter(User.is_active == True)
    return _get_verified_users(query)


def get_admin_users() -> list[User]:
    query = db.query(User).filter(User.is_admin == True)
    return _get_verified_users(query)

Magic Numbers

# Smell: Unexplained numbers
if len(password) < 8:
    raise ValueError("Password too short")

time.sleep(86400)


# Refactored: Named constants
MIN_PASSWORD_LENGTH = 8
SECONDS_PER_DAY = 86400

if len(password) < MIN_PASSWORD_LENGTH:
    raise ValueError(f"Password must be at least {MIN_PASSWORD_LENGTH} characters")

time.sleep(SECONDS_PER_DAY)

Practical Exercise

Exercise 1: Refactor Messy Code

# Before: Messy code with multiple issues
def p(d):
    r = []
    for i in d:
        if i['a'] > 0 and i['s'] == 'active':
            t = i['p'] * i['a']
            if t > 100:
                t = t * 0.9
            r.append({'n': i['n'], 't': t})
    return r

# After: Clean, readable code
from dataclasses import dataclass
from decimal import Decimal


BULK_DISCOUNT_THRESHOLD = Decimal("100")
BULK_DISCOUNT_RATE = Decimal("0.90")


@dataclass
class Product:
    name: str
    price: Decimal
    quantity: int
    status: str


@dataclass
class LineItem:
    name: str
    total: Decimal


def calculate_active_product_totals(products: list[Product]) -> list[LineItem]:
    """Calculate totals for active products with quantity > 0."""
    return [
        _create_line_item(product)
        for product in products
        if _is_purchasable(product)
    ]


def _is_purchasable(product: Product) -> bool:
    """Check if product can be purchased."""
    return product.quantity > 0 and product.status == "active"


def _create_line_item(product: Product) -> LineItem:
    """Create a line item with bulk discount applied if applicable."""
    total = product.price * product.quantity
    if total > BULK_DISCOUNT_THRESHOLD:
        total *= BULK_DISCOUNT_RATE
    return LineItem(name=product.name, total=total)

Exercise 2: Apply Factory Pattern

# Task: Create a factory for different report formats
from abc import ABC, abstractmethod


class ReportFormatter(ABC):
    @abstractmethod
    def format(self, data: dict) -> str:
        pass


class JSONFormatter(ReportFormatter):
    def format(self, data: dict) -> str:
        import json
        return json.dumps(data, indent=2)


class CSVFormatter(ReportFormatter):
    def format(self, data: dict) -> str:
        lines = [",".join(data.keys())]
        lines.append(",".join(str(v) for v in data.values()))
        return "\n".join(lines)


class HTMLFormatter(ReportFormatter):
    def format(self, data: dict) -> str:
        rows = "".join(f"<tr><td>{k}</td><td>{v}</td></tr>" for k, v in data.items())
        return f"<table>{rows}</table>"


class ReportFormatterFactory:
    _formatters = {
        "json": JSONFormatter,
        "csv": CSVFormatter,
        "html": HTMLFormatter,
    }

    @classmethod
    def create(cls, format_type: str) -> ReportFormatter:
        formatter_class = cls._formatters.get(format_type)
        if not formatter_class:
            raise ValueError(f"Unknown format: {format_type}")
        return formatter_class()

Clean Code Checklist

Use this checklist during code reviews:

• Names reveal intent

• Functions do one thing

• Functions are short (< 20 lines ideally)

• No magic numbers or strings

• No duplicate code

• Comments explain "why", not "what"

• Error handling is clean

• Code is properly formatted

• Dependencies are minimal

• Tests exist and are readable

Key Takeaways

1. Names matter - Spend time choosing clear, intention-revealing names

2. Keep functions small - One function, one responsibility

3. Avoid comments by writing clearer code - Comments are often a code smell

4. Design patterns solve recurring problems - Learn Factory, Strategy, Repository

5. Refactor continuously - Clean code is a practice, not a destination

What's Next?

Clean code principles give you the foundation. In Article 5: SOLID Principles, we'll dive deeper into object-oriented design principles and advanced patterns that help build flexible, maintainable systems.

---

This article is part of the Software Engineering 101 series.