Skip to content

Aarvion-AI/stackwise-skills / skills/engineering-rules

engineering-rules

Verified

references/readability-and-naming.md

View on GitHub
# Readability and Naming (Rule 3)

Code is read far more often than written. Optimize every line for the next reader: intention-revealing names, early returns, top-down flow, and the project's formatter as the single source of style.

## Intention-Revealing Names

A name answers "what is this?" without reading the implementation. Banned name families:

| Banned | Why | Replace with |
|--------|-----|--------------|
| `data`, `info`, `obj`, `item` | Says nothing about content | `invoices`, `userProfile`, `lineItem` |
| `tmp`, `temp`, `x`, `val` | Placeholder that shipped | The thing it holds: `normalizedEmail` |
| `handle`, `process`, `manage`, `doStuff` | Verb with no object | `retryFailedWebhooks`, `parseCsvRow` |
| `process2`, `newHelper`, `utilsV2` | Numbered variants signal unextracted duplication | Merge or rename by difference: `processRefund` |
| `flag`, `check`, `isOk` | Boolean with no predicate | `hasUnpaidInvoices`, `isRetryable` |

```typescript
// Bad
function process(data: any[]): any[] {
  const tmp = [];
  for (const item of data) {
    if (check(item)) tmp.push(handle(item));
  }
  return tmp;
}

// Good: every name states its role; the signature alone documents the function
function activeSubscribers(users: User[]): Subscriber[] {
  return users
    .filter(isSubscriptionActive)
    .map(toSubscriber);
}
```

Scope rule: the smaller the scope, the shorter the name may be. `i` is fine for a 3-line loop; a module-level export needs a full sentence-grade name.

```python
# Bad: long-lived vague name
d = load_config()
...  # 80 lines later
timeout = d["timeout"]

# Good
config = load_config()
timeout_seconds = config["timeout"]
```

## Early Returns Over Nesting

Handle failure and edge cases first, then write the happy path at the lowest indent level. Every level of nesting is a fact the reader must hold in memory.

```python
# Bad: happy path buried three levels deep
def refund(order: Order, amount: Decimal) -> Refund:
    if order is not None:
        if order.status == Status.PAID:
            if amount <= order.total:
                refund = gateway.refund(order.charge_id, amount)
                ledger.record(refund)
                return refund
            else:
                raise AmountExceedsTotalError(amount, order.total)
        else:
            raise NotPaidError(order.id)
    else:
        raise OrderNotFoundError()

# Good: guards eliminate cases one by one; happy path is unindented
def refund(order: Order, amount: Decimal) -> Refund:
    if order is None:
        raise OrderNotFoundError()
    if order.status != Status.PAID:
        raise NotPaidError(order.id)
    if amount > order.total:
        raise AmountExceedsTotalError(amount, order.total)

    refund = gateway.refund(order.charge_id, amount)
    ledger.record(refund)
    return refund
```

```go
// Same rule in Go: check-and-return is the idiom, never else-ladders
func Refund(order *Order, amount Money) (*Refund, error) {
    if order == nil {
        return nil, ErrOrderNotFound
    }
    if order.Status != StatusPaid {
        return nil, fmt.Errorf("order %s not paid: %w", order.ID, ErrNotPaid)
    }
    if amount.GreaterThan(order.Total) {
        return nil, ErrAmountExceedsTotal
    }
    r, err := gateway.Refund(order.ChargeID, amount)
    if err != nil {
        return nil, fmt.Errorf("gateway refund: %w", err)
    }
    ledger.Record(r)
    return r, nil
}
```

## Code Reads Top-Down Like Prose

A file should read like an article: the headline (public entry point) first, supporting detail below, each function calling only downward. The reader should never scroll up to understand what they just read.

```typescript
// Good: newspaper order. Read exportReport and you know the whole story;
// dig into any paragraph only if you need the detail.
export async function exportReport(runId: string): Promise<string> {
  const findings = await loadFindings(runId);
  const rows = findings.map(toCsvRow);
  return writeCsv(rows);
}

async function loadFindings(runId: string): Promise<Finding[]> { /* ... */ }
function toCsvRow(f: Finding): CsvRow { /* ... */ }
function writeCsv(rows: CsvRow[]): string { /* ... */ }
```

Within a function, keep one level of abstraction. A function that mixes `await db.query(...)` with `retryQueue.schedule(order)` is telling two stories at once; push the low-level line into a named helper so every statement sits at the same altitude.

```python
# Bad: altitudes mixed; the SQL detail interrupts the business narrative
def close_month(month: str) -> Summary:
    invoices = db.execute("SELECT * FROM invoices WHERE month = %s AND status = 'open'", [month])
    total = sum(Decimal(r["amount"]) for r in invoices)
    notify_finance(month, total)
    return Summary(month, total)

# Good
def close_month(month: str) -> Summary:
    invoices = open_invoices(month)
    total = sum(inv.amount for inv in invoices)
    notify_finance(month, total)
    return Summary(month, total)
```

## Booleans, Conditions, and Positivity

- Name predicates so the call site reads as a sentence: `if user.can_refund(order):`.
- Prefer positive names: `isEnabled` over `isNotDisabled`; double negatives (`if not is_invalid`) fail review.
- Extract multi-clause conditions into a named predicate:

```typescript
// Bad
if (user.age >= 18 && user.country === "US" && !user.flags.includes("banned") && user.kycLevel > 1) { ... }

// Good
const canTrade = user.age >= 18 && user.country === "US" && !isBanned(user) && hasCompletedKyc(user);
if (canTrade) { ... }
```

## Consistent Formatting via the Project's Formatter

Formatting is never manual and never debated in review. Find the project's formatter and run it on every change:

| Ecosystem | Format | Lint |
|-----------|--------|------|
| JS/TS | `prettier --write .` | `eslint --fix .` |
| Python | `ruff format` | `ruff check --fix` |
| Go | `gofmt -w .` / `goimports -w .` | `go vet ./...` |
| Dart/Flutter | `dart format .` | `dart analyze` |

Rules that follow from this:

- Never hand-align comments or assignments; the formatter owns whitespace.
- Never disable the formatter for a region (`// prettier-ignore`, `# fmt: off`) to preserve a personal layout; the only acceptable use is data tables whose alignment carries meaning.
- If the project has no formatter config, match the dominant existing style exactly; do not introduce a new one inside a feature PR.

## Checklist for This Reference

- [ ] No banned names (`data`, `tmp`, `handle`, `process2`, `flag`) in the diff
- [ ] Name length matches scope; module-level names are fully descriptive
- [ ] Guard clauses first; happy path at minimum indentation
- [ ] Files read top-down; no upward scrolling required to follow the flow
- [ ] Each function holds one level of abstraction
- [ ] Predicates are positive and read as sentences at the call site
- [ ] Formatter and linter run clean; no ignore pragmas added
slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack."Stars: 198kUpdated Claude CodeCodexVerifiedInstall
ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read.Stars: 194kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report.Stars: 194kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt.Stars: 194kUpdated Claude CodeCodexVerifiedInstall