coding-principles

Files (2)

• SKILL.md
• TESTS.md

SKILL.md (first lines)

<!-- sage-metadata
cost-tier: sonnet
activation: auto
tags: [execution, quality, principles, coding, implementation]
inputs: [plan-task, codebase-context]
outputs: [implementation]
requires: []
-->

# Coding Principles

Seven universal principles for writing production-quality code.
Apply these to every line, in every language. They are not a
post-hoc checklist — they shape decisions AS you write.

Stack skills (react, flutter, nextjs, etc.) add language-specific
idioms on top. These principles are the foundation.

## Principle 1: Clarity Over Cleverness

Write code a stranger can read without asking you what it does.

**Do:**
- Name things for what they DO: `fetchActiveUsers()`, `isExpired`,
  `MAX_RETRY_ATTEMPTS`
- Functions do one thing. If you need "and" to describe it, split it.
- Comments explain WHY, not WHAT. The code says what; the comment
  says why it's surprising or non-obvious.
- Prefer explicit over implicit. `if (user.role === "admin")` not
  `if (checkAccess(user, 2))`.

**Don't:**
- Magic numbers: `if (retries > 3)` → `if (retries > MAX_RETRIES)`
- Clever one-liners that save a line but cost a minute to read.
- Names like `data`, `temp`, `flag2`, `processStuff`, `handleIt`.
- Nested ternaries. Ever.

## Principle 2: Fail Loudly, Recover Gracefully

Every external call can fail. Handle it explicitly. Never swallow
errors. Give the caller something useful when things go wrong.

**Do:**
- Every `fetch`, `query`, `read`, `parse` has error handling.
- Error messages include: what happened, what was expected, what to
  do about it.
- Async operations have loading, success, AND error states. No async
  without all three.
- Distinguish recoverable (retry, fallback) from fatal (log, alert,
  stop).

**Don't:**
- Empty catch blocks. Ever. If you truly ignore an error, comment
  WHY.
- `console.log(err)` as the only error handling.
- "Failed to load" with no context. WHO failed to load WHAT and WHY.
- Retrying fatal errors. Crashing on recoverable ones.

## Principle 3: Guard the Boundaries

Validate at every entry point. Don't trust input from users, APIs,
files, or even your own internal modules.

**Do:**
- Public function parameters: validate type, range, presence.
- API responses: check shape before accessing nested fields.
  `response?.data?.user?.id` not `response.data.user.id`.
- User input: validate before processing. Reject early, clearly.
- Configuration: fail at startup if config is invalid, not at 3am
  when the missing value is first accessed.
- Database results: handle empty results, null fields, unexpected types.

**Don't:**
- Trust that an API response has the shape you expect.
- Access nested properties without null checks.
- Process user input without validation.
- Assume config values exist without checking.

## Principle 4: Smallest Scope, Shortest Lifetime

Variables close to where they're used. Functions close to what
calls them. Reduce the blast radius of every change.

**Do:**
- Declare variables at first use, not at the top.
- Prefer local over global. Prefer parameters over shared state.
- Prefer pure functions (same input → same output) where practical.
- Keep functions short. If you're scrolling, it's too long. Extract.
- Modules have one reason to change.

**Don't:**
- Declare all variables at the top of the function.
- Use global state when a parameter would work.
- Write 200-line functions. Extract logical sections.
- Put unrelated functionality in the same module because
  "it's convenient."

## Principle 5: Make the Right Thing Easy, the Wrong Thing Hard

Design APIs and interfaces so correct usage is obvious and misuse
requires effort.

**Do:**
- Required parameters come first. Optional parameters have defaults.
- Return types that force the caller to handle success and failure.
- Use the type system: enum not string, branded types for IDs,
  non-nullable when null is invalid.
- Impossible states should be unrepresentable.

**Don't:**
- Return `null` to mean both "failed" and "empty."
- Accept `any` or untyped dictionaries for structured data.
- Design functions where the caller must remember to check a flag.
- Allow invalid state combinations that crash at runtime.

## Principle 6: Consistency Beats Perfection

Match the existing codebase. Consistency across the project matters
more than your personal preference.

From xoai/sage, MIT.

More from xoai/sage