ffsshhttiikk Clean Code
What I do
I help developers write code that is easy to understand, maintain, and extend. Clean code is about respecting both machines and humans—code that works correctly today and can be understood and modified by other developers (or your future self) tomorrow. I encompass naming conventions, function design, formatting, error handling, and overall code organization that prioritizes clarity over cleverness.
When to use me
Apply clean code principles to all production code that will be maintained over time. Clean code matters most in collaborative environments where multiple developers read and modify the same codebase. Use these practices when writing new features, during code reviews, when debugging, or when refactoring legacy code. Avoid over-engineering one-off scripts or exploratory code where maintainability is not a concern.
Core Concepts
- Meaningful Names: Names should reveal intent, be pronounceable, and be searchable
- Functions: Functions should do one thing, do it well, and be small
- Comments: Code should explain itself; comments should explain "why", not "what"
- Formatting: Consistent formatting improves readability and shows respect for code
- Error Handling: Handle errors gracefully without masking bugs
- Objects vs Data Structures: Use objects to hide data, expose behavior
- Boundaries: Keep external APIs clean and minimize dependencies
- Unit Tests: Clean tests that are readable and fast
- Refactoring: Continuous improvement of existing code
- Emergent Design: Good architecture emerges from simple, well-designed parts
Code Examples
Meaningful Naming
from datetime import datetime, timedelta
# Bad
def get_things(a, b):
lst = []
for i in range(a):
for x in lst:
if x.status == 1:
x.status = 2
return lst
# Good
class Task:
def __init__(self, task_id: int, title: str):
self.task_id = task_id
self.title = title
self.status: TaskStatus = TaskStatus.PENDING
class TaskStatus:
PENDING = 1
IN_PROGRESS = 2
COMPLETED = 3
def activate_pending_tasks(
tasks: list[Task],
days_ago: int = 30
) -> list[Task]:
cutoff_date = datetime.now() - timedelta(days=days_ago)
activated_tasks: list[Task] = []
for task in tasks:
if task.status == TaskStatus.PENDING:
task.status = TaskStatus.IN_PROGRESS
activated_tasks.append(task)
return activated_tasks
Small Functions
from decimal import Decimal
from typing import Optional
# Bad - One function doing too much
def process_order(order_data: dict) -> dict:
validate_order(order_data)
calculate_totals(order_data)
apply_discounts(order_data)
save_order(order_data)
send_confirmation(order_data)
update_inventory(order_data)
return order_data
# Good - Each function does one thing
def validate_order(order_data: dict) -> None:
required_fields = ["customer_id", "items", "shipping_address"]
for field in required_fields:
if field not in order_data:
raise ValueError(f"Missing required field: {field}")
def calculate_order_totals(order: dict) -> None:
subtotal = sum(item["price"] * item["quantity"] for item in order["items"])
tax = subtotal * Decimal("0.08")
order["subtotal"] = subtotal
order["tax"] = tax
order["total"] = subtotal + tax
def apply_discounts(order: dict, discount_code: Optional[str] = None) -> None:
if discount_code == "SAVE10":
order["total"] *= Decimal("0.9")
order["discount_applied"] = True
def process_order(order_data: dict, discount_code: Optional[str] = None) -> dict:
validate_order(order_data)
calculate_order_totals(order_data)
apply_discounts(order_data, discount_code)
saved_order = save_order(order_data)
send_confirmation(saved_order)
update_inventory(saved_order)
return saved_order
Proper Error Handling
from contextlib import contextmanager
from typing import Generator
class InsufficientFundsError(Exception):
def __init__(self, balance: float, withdrawal: float):
self.balance = balance
self.withdrawal = withdrawal
super().__init__(f"Insufficient funds: {balance} < {withdrawal}")
class AccountClosedError(Exception):
pass
class BankAccount:
def __init__(self, account_id: str, initial_balance: float = 0):
self.account_id = account_id
self._balance = Decimal(str(initial_balance))
self._is_active = True
@property
def balance(self) -> float:
return float(self._balance)
def deposit(self, amount: float) -> None:
if amount <= 0:
raise ValueError("Deposit amount must be positive")
if not self._is_active:
raise AccountClosedError(self.account_id)
self._balance += Decimal(str(amount))
def withdraw(self, amount: float) -> None:
if amount <= 0:
raise ValueError("Withdrawal amount must be positive")
if not self._is_active:
raise AccountClosedError(self.account_id)
if amount > self._balance:
raise InsufficientFundsError(float(self._balance), amount)
self._balance -= Decimal(str(amount))
@contextmanager
def managed_account(account: BankAccount) -> Generator[BankAccount, None, None]:
try:
yield account
except Exception as e:
print(f"Error managing account {account.account_id}: {e}")
raise
Writing Self-Documenting Code
from datetime import datetime
from typing import NamedTuple
class UserCredentials(NamedTuple):
username: str
password_hash: str
salt: str
class AuthenticationResult(NamedTuple):
success: bool
user_id: int | None = None
error_message: str | None = None
class PasswordHasher:
@staticmethod
def hash(password: str, salt: str) -> str:
import hashlib
return hashlib.sha256(f"{password}{salt}".encode()).hexdigest()
@staticmethod
def verify(
password: str,
salt: str,
expected_hash: str
) -> bool:
return PasswordHasher.hash(password, salt) == expected_hash
def authenticate_user(
credentials: UserCredentials,
stored_credentials: dict[str, UserCredentials]
) -> AuthenticationResult:
if credentials.username not in stored_credentials:
return AuthenticationResult(success=False)
stored = stored_credentials[credentials.username]
if not PasswordHasher.verify(
credentials.password,
stored.salt,
stored.password_hash
):
return AuthenticationResult(success=False)
return AuthenticationResult(success=True, user_id=hash(credentials.username))
Type Hints and Structure
from dataclasses import dataclass
from enum import Enum
from typing import Protocol, runtime_checkable
class OrderStatus(Enum):
PENDING = "pending"
CONFIRMED = "confirmed"
SHIPPED = "shipped"
DELIVERED = "delivered"
CANCELLED = "cancelled"
@dataclass(frozen=True)
class OrderItem:
product_id: str
quantity: int
unit_price: float
@property
def total_price(self) -> float:
return self.quantity * self.unit_price
@dataclass
class ShippingAddress:
street: str
city: str
state: str
zip_code: str
country: str
@dataclass
class Order:
order_id: str
customer_id: str
items: list[OrderItem]
shipping_address: ShippingAddress
status: OrderStatus = OrderStatus.PENDING
created_at: datetime = None
@property
def total_amount(self) -> float:
return sum(item.total_price for item in self.items)
@runtime_checkable
class OrderRepository(Protocol):
def save(self, order: Order) -> None:
pass
def find_by_id(self, order_id: str) -> Order | None:
pass
Best Practices
- Name Variables Meaningfully: Use descriptive names that reveal intent
- Functions Should Do One Thing: Each function should have a single responsibility
- Keep Functions Small: Functions should rarely exceed 20 lines
- Avoid Magic Numbers: Use named constants instead of literal numbers
- Use Type Hints: Make expected types explicit
- Write Self-Documenting Code: Code should explain itself
- Handle Errors Explicitly: Don't swallow exceptions silently
- Comment Why, Not What: Explain intent, not implementation
- Format Consistently: Use automated formatters
- Refactor Ruthlessly: Continuous improvement prevents technical debt
- Delete Dead Code: Unused code confuses and bloats
- Tests Document Behavior: Tests serve as documentation