clean-code

name	clean-code
description	Clean code principles and best practices
license	MIT
compatibility	opencode
metadata	{"audience":"developers","category":"code-quality"}

What I do

• Write readable and maintainable code
• Apply SOLID principles
• Use meaningful names for variables, functions, and classes
• Keep functions small and focused
• Write proper comments and documentation
• Handle errors gracefully
• Remove dead code and duplication
• Follow DRY (Don't Repeat Yourself)

When to use me

When writing or refactoring code for better quality and readability.

Meaningful Names

# BAD - unclear what these represent
d = 12
x = get_data()
tmp = calculate()

# GOOD - clear and descriptive
elapsed_days = 12
user_data = fetch_active_users()
temporary_cache = calculate_recent_stats()


# BAD - unclear function purpose
def process(x):
    if x > 10:
        return True
    return False


# GOOD - descriptive function name
def is_above_threshold(value: int, threshold: int = 10) -> bool:
    """Check if value exceeds the given threshold."""
    return value > threshold


# BAD - vague class name
class Handler:
    def handle(self):
        pass


# GOOD - specific class name
class OrderProcessor:
    def process_order(self, order: Order) -> None:
        """Process a single order through the pipeline."""
        self.validate_order(order)
        self.calculate_totals(order)
        self.apply_discounts(order)
        self.finalize_order(order)


# Constants should explain their purpose
# BAD
RATE = 0.5
LIMIT = 1000

# GOOD
DISCOUNT_RATE = 0.5
MAX_ITEMS_PER_ORDER = 1000

Small Functions

# BAD - function does too many things
def process_order(order_data: dict) -> Order:
    validate_input(order_data)
    calculate_prices(order_data)
    apply_discounts(order_data)
    save_to_database(order_data)
    send_confirmation_email(order_data)
    update_inventory(order_data)
    return order


# GOOD - each function has a single responsibility
def create_order(order_data: dict) -> Order:
    validated_data = validate_order_data(order_data)
    order = build_order(validated_data)
    order = apply_pricing_rules(order)
    order = save_order(order)
    send_order_confirmation(order)
    update_inventory_for(order)
    return order


def validate_order_data(data: dict) -> dict:
    required_fields = ['customer_id', 'items', 'shipping_address']
    for field in required_fields:
        if field not in data:
            raise ValidationError(f"Missing required field: {field}")
    return data


def build_order(data: dict) -> Order:
    return Order(
        customer_id=data['customer_id'],
        items=data['items'],
        shipping_address=data['shipping_address'],
    )

Error Handling

# BAD - unclear error handling
def get_user(id):
    try:
        return db.query(User).get(id)
    except Exception as e:
        log.error(e)
        return None


# GOOD - specific exceptions, proper handling
class UserNotFoundError(Exception):
    """Raised when a user cannot be found."""
    pass


def get_user_by_id(user_id: str) -> User:
    """
    Retrieve a user by their unique identifier.

    Args:
        user_id: The user's unique ID

    Returns:
        User instance

    Raises:
        UserNotFoundError: If user doesn't exist
        DatabaseError: On database connection issues
    """
    try:
        user = user_repository.find_by_id(user_id)
        if user is None:
            raise UserNotFoundError(f"User {user_id} not found")
        return user
    except DatabaseConnectionError:
        logger.error("Database connection failed")
        raise  # Re-raise for caller to handle

Comments

# BAD - comments that don't add value
# Increment i by 1
i += 1

# Get the user's name
name = user.get_name()


# GOOD - explain WHY, not WHAT
# Rate limit exceeded, user must wait before retrying
# This prevents API abuse while allowing legitimate traffic
if request_count >= MAX_REQUESTS:
    raise RateLimitExceededError()


# GOOD - complex logic explained
# Boyer-Moore majority vote algorithm
# Finds candidate with more than n/2 occurrences in O(n) time
def find_majority_candidate(elements: list) -> Optional[element]:
    if not elements:
        return None

    count = 0
    candidate = None

    for element in elements:
        if count == 0:
            candidate = element
            count = 1
        elif element == candidate:
            count += 1
        else:
            count -= 1

    return candidate


# GOOD - document public APIs
def calculate_shipping_cost(
    weight: float,
    destination: str,
    shipping_method: ShippingMethod = ShippingMethod.STANDARD,
) -> float:
    """
    Calculate shipping cost based on package weight and destination.

    Args:
        weight: Package weight in kilograms (min: 0.1, max: 100.0)
        destination: ISO 3166-1 alpha-2 country code
        shipping_method: Selected shipping speed option

    Returns:
        Shipping cost in the system's base currency

    Raises:
        ValueError: If weight is outside valid range
        UnsupportedDestinationError: If destination is not serviceable

    Example:
        >>> calculate_shipping_cost(2.5, 'US', ShippingMethod.EXPRESS)
        15.99
    """

DRY Principle

# BAD - code duplication
def create_user(name, email):
    validate_name(name)
    validate_email(email)
    user = User(name=name, email=email)
    db.save(user)
    send_welcome_email(email)
    return user


def create_admin(name, email):
    validate_name(name)
    validate_email(email)
    admin = Admin(name=name, email=email)
    db.save(admin)
    send_welcome_email(email)
    return admin


# GOOD - extract common logic
class BaseUserFactory:
    @staticmethod
    def validate_input(name: str, email: str):
        validate_name(name)
        validate_email(email)

    @staticmethod
    def send_welcome_notification(email: str):
        send_welcome_email(email)


class UserFactory(BaseUserFactory):
    def create(self, name: str, email: str) -> User:
        self.validate_input(name, email)
        user = User(name=name, email=email)
        db.save(user)
        self.send_welcome_notification(email)
        return user


class AdminFactory(BaseUserFactory):
    def create(self, name: str, email: str) -> Admin:
        .validate_input(name, email)
        admin = Admin(name=name, email=email)
        db.save(admin)
        .send_welcome_notification(email)
         admin

SOLID Principles

# S - Single Responsibility
# O - Open/Closed
# L - Liskov Substitution
# I - Interface Segregation
# D - Dependency Inversion


# BAD - violates SRP and OCP
class ReportGenerator:
    def generate(self, data: list, format: str):
        if format == 'pdf':
            self._generate_pdf(data)
        elif format == 'excel':
            self._generate_excel(data)
        elif format == 'csv':
            self._generate_csv(data)


# GOOD - SRP + OCP with strategy pattern
from abc import ABC, abstractmethod


class ReportFormat(ABC):
    @abstractmethod
    def generate(self, data: list) -> bytes:
        pass


class PDFFormat(ReportFormat):
    def generate(self, data: list) -> bytes:
        # PDF generation logic
        return 


 ():
     () -> :
        
           


 :
     () -> :
        . = 

     () -> :
         ..generate(data)



 ():
     () -> User: ...
     () -> : ...


 :
     () -> :
        .repository = repository