AI Code Maintainability

AI Code Maintainability — Write Code That Survives

The core problem: AI agents optimize for "works on first run." Maintenance bugs appear 3–6 months later when context is gone, requirements shift, or edge cases hit prod.

The 15 Patterns That Kill Maintainability

1. Silent Error Swallowing (most dangerous)

# ❌ AI generates this — crashes silently in prod
try:
    result = call_external_api(data)
except:
    pass

# ✅ Always log + re-raise or return error state
import logging
logger = logging.getLogger(__name__)

try:
    result = call_external_api(data)
except ExternalAPIError as e:
    logger.error("API call failed: %s | data=%s", e, data, exc_info=True)
    raise  # or: return Result.error(str(e))
except Exception as e:
    logger.critical("Unexpected error in call_external_api: %s", e, exc_info=True)
    raise

2. Bare except / Pokémon Exception Handling

# ❌ Catches KeyboardInterrupt, SystemExit, MemoryError — everything
try:
    do_work()
except Exception:  # still too broad
    return None    # swallowed silently

# ✅ Catch specific exceptions, handle each explicitly
try:
    do_work()
except ValueError as e:
    logger.warning("Invalid input: %s", e)
    return default_value
except NetworkError as e:
    logger.error("Network failure: %s", e)
    raise RetryableError(f"Network unavailable: {e}") from e

3. Magic Numbers and Strings

# ❌ What is 300? What is "active"?
if user.age > 300:
    status = "active"
time.sleep(300)

# ✅ Named constants with explanations
MAX_VALID_AGE_YEARS = 150  # ISO 8601 human lifespan upper bound
ACTIVE_STATUS = "active"
CACHE_REFRESH_INTERVAL_SECONDS = 300  # 5-minute cache TTL per SLA

if user.age > MAX_VALID_AGE_YEARS:
    status = ACTIVE_STATUS
time.sleep(CACHE_REFRESH_INTERVAL_SECONDS)

4. print() Instead of Structured Logging

# ❌ No timestamp, no level, no context, can't filter in prod
print(f"Processing user {user_id}")
print("ERROR: something failed")

# ✅ Structured logging — searchable in Datadog/CloudWatch/Grafana
import logging
logger = logging.getLogger(__name__)

logger.info("Processing user", extra={"user_id": user_id, "action": "process"})
logger.error("Processing failed", extra={"user_id": user_id}, exc_info=True)

5. Missing Type Hints (Python / TypeScript)

# ❌ Future maintainer has no idea what this accepts/returns
def process_data(data, config, mode=None):
    ...

# ✅ Self-documenting — IDE and mypy catch errors immediately
from typing import Optional
from dataclasses import dataclass

def process_data(
    data: list[dict[str, str]],
    config: ProcessConfig,
    mode: Optional[ProcessMode] = None,
) -> ProcessResult:
    ...

// ❌ any disables the type system
function processUser(data: any): any {
  return data.profile.name;
}

// ✅ Full types — TypeScript catches data.profile?.name at compile time
interface User { id: string; profile: { name: string; email: string } }
interface ProcessResult { displayName: string; emailHash: string }

function processUser(data: User): ProcessResult {
  return { displayName: data.profile.name, emailHash: hash(data.profile.email) };
}

6. Mutable Default Arguments (Python silent bug)

# ❌ Classic Python bug — list shared across ALL calls
def add_item(item, items=[]):  # same [] object forever
    items.append(item)
    return items

add_item("a")  # ["a"]
add_item("b")  # ["a", "b"]  ← not ["b"]!

# ✅ None sentinel pattern
def add_item(item: str, items: list[str] | None = None) -> list[str]:
    if items is None:
        items = []
    items.append(item)
    return items

7. Hardcoded Paths and Environment Values

# ❌ Breaks in Docker, in CI, on another dev's machine
DATA_PATH = "/home/user/projects/myapp/data"
API_URL = "http://localhost:8000"

# ✅ Environment-driven — works everywhere
import os
from pathlib import Path

DATA_PATH = Path(os.environ.get("DATA_PATH", "./data")).resolve()
API_URL = os.environ.get("API_URL", "http://localhost:8000")

if not os.environ.get("API_URL"):
    raise EnvironmentError("API_URL must be set. Example: export API_URL=https://api.prod.com")

8. No Retry / Timeout on External Calls

# ❌ Hangs forever if service is slow; crashes on first transient error
response = requests.get(f"{API_URL}/users/{user_id}")
data = response.json()

# ✅ Timeout + retry with exponential backoff
import requests
from tenacity import retry, stop_after_attempt, wait_exponential, retry_if_exception_type

@retry(
    retry=retry_if_exception_type((requests.Timeout, requests.ConnectionError)),
    wait=wait_exponential(multiplier=1, min=1, max=30),
    stop=stop_after_attempt(3),
)
def fetch_user(user_id: str) -> dict:
    response = requests.get(
        f"{API_URL}/users/{user_id}",
        timeout=(3.05, 27),   # (connect_timeout, read_timeout)
    )
    response.raise_for_status()
    return response.json()

9. Unvalidated External Input

# ❌ Crashes or does wrong thing on unexpected input
def create_user(data: dict) -> User:
    return User(
        name=data["name"],
        email=data["email"],
        age=data["age"],
    )

# ✅ Validate at system boundary — fail fast with clear message
from pydantic import BaseModel, EmailStr, Field

class CreateUserRequest(BaseModel):
    name: str = Field(min_length=1, max_length=100)
    email: EmailStr
    age: int = Field(ge=0, le=150)

def create_user(raw_data: dict) -> User:
    req = CreateUserRequest.model_validate(raw_data)  # raises ValidationError with details
    return User(name=req.name, email=req.email, age=req.age)

10. Uncaught Promise Rejections (TypeScript/JS)

// ❌ Unhandled rejection crashes Node.js silently in some versions
async function loadData() {
  const data = await fetchFromAPI();  // what if this throws?
  return data;
}
// Caller: loadData()  ← no await, no .catch()

// ✅ Always handle async errors
async function loadData(): Promise<Result<Data, AppError>> {
  try {
    const data = await fetchFromAPI();
    return { ok: true, data };
  } catch (error) {
    logger.error("Failed to load data", { error });
    return { ok: false, error: new AppError("DATA_LOAD_FAILED", String(error)) };
  }
}

// Caller always handles:
const result = await loadData();
if (!result.ok) return handleError(result.error);

11. Resource Leaks (File/DB/Connection)

# ❌ File not closed if exception thrown
f = open("data.csv")
data = f.read()
process(data)
f.close()  # never reached if process() throws

# ✅ Context manager guarantees cleanup
with open("data.csv", "r", encoding="utf-8") as f:
    data = f.read()

# ✅ Async version
async with aiofiles.open("data.csv") as f:
    data = await f.read()

12. N+1 Query Problem (AI loves loops over DB)

# ❌ N queries for N users — kills prod at scale
users = db.query(User).all()
for user in users:
    orders = db.query(Order).filter(Order.user_id == user.id).all()  # N queries
    send_summary(user, orders)

# ✅ Eager load with JOIN — 1 query total
from sqlalchemy.orm import joinedload

users = db.query(User).options(joinedload(User.orders)).all()
for user in users:
    send_summary(user, user.orders)  # already loaded

13. Sleeping Instead of Polling with Backoff

# ❌ Fixed sleep — either too fast (hammers API) or too slow
while True:
    status = check_job_status(job_id)
    if status == "done":
        break
    time.sleep(5)

# ✅ Exponential backoff with max cap
import time

def wait_for_job(job_id: str, max_wait: int = 300) -> JobResult:
    delay = 1
    elapsed = 0
    while elapsed < max_wait:
        status = check_job_status(job_id)
        if status.is_terminal():
            return status
        logger.debug("Job %s status=%s, retrying in %ds", job_id, status, delay)
        time.sleep(delay)
        elapsed += delay
        delay = min(delay * 2, 30)   # cap at 30s
    raise TimeoutError(f"Job {job_id} did not complete within {max_wait}s")

14. Implicit Dependencies Between Modules

# ❌ Module A depends on global state set by module B — breaks on import order change
# in config.py
DATABASE_URL = None

# in main.py
from config import *
DATABASE_URL = os.environ["DATABASE_URL"]  # set globally

# in users.py — only works if main.py ran first
from config import DATABASE_URL
db = connect(DATABASE_URL)  # None if imported before main.py init

# ✅ Explicit dependency injection
class UserRepository:
    def __init__(self, db_url: str):
        self.db = connect(db_url)

# main.py wires everything
db_url = os.environ["DATABASE_URL"]
user_repo = UserRepository(db_url=db_url)

15. No Idempotency on Write Operations

# ❌ Double-click / retry creates duplicate records
def create_order(user_id: str, items: list) -> Order:
    order = Order(user_id=user_id, items=items)
    db.add(order)
    db.commit()
    return order

# ✅ Idempotency key prevents duplicates
def create_order(user_id: str, items: list, idempotency_key: str) -> Order:
    existing = db.query(Order).filter(
        Order.idempotency_key == idempotency_key
    ).first()
    if existing:
        return existing   # same result, no duplicate

    order = Order(user_id=user_id, items=items, idempotency_key=idempotency_key)
    db.add(order)
    db.commit()
    return order

Pre-Write Checklist (run mentally before every function)

□ What happens when the external call fails? (error path written?)
□ What happens with empty input / null / zero?
□ Will this work in 6 months without the original context? (self-documenting?)
□ Are all "magic" values named constants?
□ Does every exception get logged with context?
□ Are all required env vars validated at startup, not at use time?
□ If this function is called twice, does it produce the same result?
□ Can this be tested without the real DB/API/filesystem?

Self-Review Protocol (before handing off code)

# Run this mental filter on every file written:

MAINTAINABILITY_CHECKLIST = {
    "error_handling": "Every try block has a specific except with logging",
    "type_safety":    "All function params and returns are typed",
    "constants":      "No unexplained numeric or string literals",
    "logging":        "Structured logger used, not print()",
    "env_config":     "All config comes from env vars with startup validation",
    "timeouts":       "All external calls have explicit timeout values",
    "idempotency":    "Write operations are safe to retry",
    "resource_mgmt":  "All file/db/connection handles use context managers",
    "no_globals":     "No mutable global state; deps injected explicitly",
    "testability":    "Can I unit-test this without real external systems?",
}

Anti-Fake-Pass Checks

• Code runs ≠ code is production-safe — always apply checklist
• Catching Exception is still too broad for most cases — catch specific types
• logger.error("failed") with no context is nearly useless — log IDs, inputs, stack
• Type hints on just the happy path but Optional not handled = hidden None crashes
• Passing tests doesn't mean idempotency — tests usually don't test double-submit
• "Works in dev" with env vars from .env file ≠ works in prod with missing vars