What Good Code Actually Looks Like: Engineering Craft Beyond the Linter

"Good code" is a phrase everyone uses and almost no one defines precisely. In interviews and on teams, it gets used as a proxy for "code I would have written" — which is not a useful definition.

The six dimensions that actually matter, in the order they should be prioritized:

1. Correctness. The code does what it is supposed to do, including in edge cases and under failure conditions. Non-negotiable; supersedes all other dimensions.

2. Clarity. The code communicates its intent clearly to the future reader — not the author. This is the most underrated dimension and the one that most differentiates senior from junior code.

3. Error handling. Errors are treated as first-class citizens: explicitly named, explicitly handled, explicitly surfaced to the caller. The most common quality failure in production codebases is not algorithmic bugs — it is silenced exceptions and missing error paths.

4. Testability. The code is designed to be tested without excessive mocking, global state, or access to internal details. Testability is an architectural property, not a testing afterthought.

5. Performance awareness. The code is not gratuitously inefficient, and the author is aware of where the expensive operations are. This does not mean premature optimization — it means not writing O(N²) where O(N) exists, and not making 1,000 database calls where 1 would work.

6. Maintainability. The code will be easy to change correctly six months from now. This is the dimension most affected by the other five.

These dimensions are in tension. Maximizing clarity can reduce performance. Maximum testability can require more abstraction than clarity prefers. Good engineering judgment is knowing which dimension to optimize for in context — and making that trade-off explicit rather than implicit.

Phil Karlton's observation that "there are only two hard things in computer science: cache invalidation and naming things" has endured because it is precisely correct. Bad naming is the most pervasive quality problem in production codebases, and it compounds over time as each new developer reads the bad name and interprets it differently.

The naming test: Can the reader understand what this variable/function/class contains or does without reading any other code? If the answer is no, the name is wrong.

Common naming failures and their fixes:

Abbreviations that require context: usr, dt, cfg, msg. Use full names: user, date_range, database_config, error_message.

Generic names that describe structure instead of content: data, result, temp, obj, list. These say what the thing is syntactically without saying what it is semantically. validated_user_record, checkout_session, pending_transactions are semantic names.

Boolean names that don't read as booleans: status, flag, enabled. Prefer the is/has/can/should prefix: is_active, has_permission, can_checkout, should_retry.

Function names that describe implementation instead of intent: process_data, handle_request, do_thing. Name functions by what they return or accomplish: validate_payment_details, fetch_user_by_email, calculate_tax_for_region.

Names that lie: get_user that creates a user if one doesn't exist. validate_config that also applies the config. send_notification that also logs the notification. These are the worst category — they produce bugs that are hard to trace because the code appears to do one thing while doing another.

The most common quality failure in production Python and TypeScript codebases is not wrong algorithms — it is swallowed exceptions and silent error paths. Code that works correctly on the happy path but fails invisibly on any error condition.

The three tiers of error handling quality:

(1) Ignore the error (the worst):

try:
    result = payment_gateway.charge(amount)
except Exception:
    pass  # ← This is a bug in every codebase it appears in

The caller has no way to know the charge failed. The user sees a success message. The charge did not happen.

(2) Log and re-raise (acceptable for infrastructure code):

try:
    result = payment_gateway.charge(amount)
except PaymentGatewayError as e:
    logger.error("Payment charge failed", extra={"amount": amount, "error": str(e)})
    raise  # Re-raises the original exception with its traceback intact

Logging is not error handling — it is observation. The caller still needs to handle the failure.

(3) Explicit typed errors surfaced to the caller (production standard):

class PaymentDeclined(Exception):
    def __init__(self, reason: str, decline_code: str) -> None:
        self.reason = reason
        self.decline_code = decline_code

def charge_payment_method(amount_cents: int, payment_method_id: str) -> ChargeResult:
    try:
        return gateway.charge(amount_cents, payment_method_id)
    except GatewayDeclineError as e:
        raise PaymentDeclined(reason=e.message, decline_code=e.code) from e
    except GatewayTimeoutError as e:
        raise PaymentServiceUnavailable(retry_after_seconds=30) from e

The caller knows exactly what can go wrong, can handle each case appropriately, and is not required to read the implementation to know what exceptions to expect.

The golden rule: Every function that can fail should either return an explicit error type (Result pattern) or raise a named exception that the caller can catch. Silent failures — returning None, returning empty, catching and ignoring — are bugs waiting to be discovered in production.

The Single Responsibility Principle is one of the most cited and least understood principles in software engineering. The common misunderstanding: "a function should do one thing." The useful definition: a function/class should have one reason to change.

In practice, the test is: if requirements change in a specific way, how many functions do I need to modify? If the answer is "many functions scattered across the codebase," the responsibility is not localized.

The pattern that violates SRP most often: functions that combine data retrieval with data transformation with side effects.

# ❌ Three reasons to change: the query changes, the format changes, or the side effect changes
def get_and_process_orders(user_id: int) -> None:
    orders = db.query("SELECT * FROM orders WHERE user_id = ?", user_id)
    processed = [{"id": o["id"], "total": o["price"] * o["qty"]} for o in orders]
    cache.set(f"orders:{user_id}", processed)
    email_service.send_summary(user_id, processed)

# ✅ Each function has exactly one reason to change
def fetch_raw_orders(user_id: int) -> list[RawOrder]:
    return db.query("SELECT * FROM orders WHERE user_id = ?", user_id)

def calculate_order_totals(raw_orders: list[RawOrder]) -> list[OrderSummary]:
    return [OrderSummary(id=o.id, total=o.price * o.quantity) for o in raw_orders]

def cache_order_summaries(user_id: int, summaries: list[OrderSummary]) -> None:
    cache.set(f"orders:{user_id}", summaries)

def send_order_summary_email(user_id: int, summaries: list[OrderSummary]) -> None:
    email_service.send_summary(user_id, summaries)

The separated version has four functions instead of one. The payoff: calculate_order_totals is now pure — no database, no cache, no email — and can be tested with zero mocking. The query can change without touching the transformation. The email behavior can change without touching the cache. Each function has exactly one reason to change.

The rule of three: If you find yourself copy-pasting a block of code a third time, extract it into a named function. The name is the value — it documents what the block is doing and gives the future reader a handle to understand it. Extract at the third duplication, not the second: two instances of similar code might be genuinely different; three is a pattern.

The most useful mental model for comments: comments explain why, code explains what.

If a reader needs a comment to understand what a piece of code does, the code is not clear enough. Rename the variables, extract the function, or simplify the logic until the code itself communicates its intent. A comment that says "// increment the counter" is noise — the code already says counter += 1.

The four cases where comments genuinely add value:

(1) Non-obvious decisions. When you made a choice that a future engineer will question, explain it.

# Sleep for 100ms before retry to avoid thundering herd against the payment gateway.
# The gateway rate-limits at 500 req/s; at our peak traffic of 450 req/s, without
# backoff all retries would arrive simultaneously and trigger a second rate limit.
time.sleep(0.1)

(2) Links to external context. Bug reports, spec documents, or known limitations that are not captured in the code.

# Stripe rounds to the nearest cent in certain currencies (JPY, HUF) — do not
# apply our own rounding before passing to the gateway or we get double-rounding.
# See: https://stripe.com/docs/currencies#zero-decimal

(3) Known limitations or invariants. Preconditions the caller must satisfy, or postconditions the function guarantees.

def calculate_shipping_rate(weight_kg: float, destination: Address) -> Money:
    # Assumes weight_kg > 0 and destination.country is a valid ISO 3166 code.
    # Returns a non-negative Money amount in the destination country's currency.
    ...

(4) Performance rationale. When an unusual implementation exists for performance reasons, document it so the next engineer does not "simplify" it away.

# Using a set instead of a list here: membership checks are O(1) vs O(N).
# At ~10K items per request, the list version took ~80ms; the set version takes ~0.1ms.
seen_user_ids: set[int] = set()

Comments that should be deleted:

# Returns the user             ← the function name already says this
# Loop through the orders      ← the code shows this
# TODO: fix this               ← create a ticket instead; comments don't get resolved
# This is a hack               ← explain why it's a hack and what the right fix is

Performance awareness does not mean premature optimization. It means: before you write code that runs in a loop, a hot path, or a tight deadline, you know what the expensive operations are and you have not placed them carelessly.

The three performance anti-patterns that appear in every codebase:

(1) N+1 queries. The single most common production performance bug. A loop that fetches related data inside the loop body:

# ❌ N+1: 1 query for orders + N queries for each order's user
orders = Order.objects.filter(status="pending")
for order in orders:
    user = User.objects.get(id=order.user_id)  # 1 query per order
    print(f"{user.email}: {order.total}")

# ✅ 2 queries total regardless of order count
orders = Order.objects.filter(status="pending").select_related("user")
for order in orders:
    print(f"{order.user.email}: {order.total}")  # no additional queries

(2) Sequential I/O where concurrent is possible. HTTP calls, database queries, or file reads that can run in parallel but are written sequentially:

# ❌ Sequential: 3 × API latency (~300ms total if each takes 100ms)
user = fetch_user(user_id)
orders = fetch_orders(user_id)
preferences = fetch_preferences(user_id)

# ✅ Concurrent: max(API latency) (~100ms total)
user, orders, preferences = await asyncio.gather(
    fetch_user(user_id),
    fetch_orders(user_id),
    fetch_preferences(user_id),
)

(3) Repeated computation in a loop. A function call whose result does not change across iterations being called inside the loop:

# ❌ Calls len(blocked_users) on every iteration — O(N) if blocked_users is a list
for user in all_users:
    if len(blocked_users) > 0 and user.id in blocked_users:
        ...

# ✅ Compute once, outside the loop. Use a set for O(1) membership checks.
blocked_user_ids = set(u.id for u in blocked_users)  # computed once
for user in all_users:
    if user.id in blocked_user_ids:  # O(1) lookup
        ...

The guideline: before writing any loop over a collection that might be large, ask — am I making a network call or database query inside this loop? If yes, find the batch API or restructure the query to fetch all data before the loop.