coding-principles

<!-- 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. **Do:** - Read existing code before writing new code. Match patterns. - Follow the project's error handling pattern. - Use the project's existing utilities before writing new ones. - If the project has no patterns, establish one and follow it. - Match naming: if the project uses `camelCase`, use `camelCase`. **Don't:** - Introduce a new style in your files because "it's better." - Write a utility function when one already exists in the project. - Mix patterns: callbacks in one file, promises in another, async/await in a third. ## Principle 7: Test What Matters, Not What's Easy Write tests that catch bugs, not tests that inflate coverage numbers. **Do:** - Test the contract: "given X input, expect Y output." - Test boundaries: min, max, zero, empty, one, many. - Test error paths: invalid input, timeout, permission denied. - One assertion per test when practical. - Test names describe the scenario: `test_expired_token_returns_401`. **Don't:** - Test implementation details: "function calls helper A then B." - Test only the happy path. - Name tests `test_1`, `test_auth_3`, `test_new`. - Write tests that pass regardless of the implementation being correct. - Mock everything — some integration is worth testing. ## How This Loads Build-loop loads this capability at Step 3, before each task: ``` Sage: Loading coding principles for implementation. Following: clarity, error handling, boundary guards, minimal scope, safe APIs, consistency, behavior testing. ``` These principles are active for every line written during the task. They are NOT a post-hoc checklist — they shape the code as it's written. The announcement `Loading coding principles for implementation.` is the compliance marker: it MUST appear before each task's implementation, making the standard active and observable rather than assumed. ## Rationalization table Derived from the RED baseline in `TESTS.md` — the excuses for skipping the load step and just coding. The marker must appear on every task, no size exception. | The excuse (observed) | Why it's wrong | The rule | |---|---|---| | "It's a tiny change, principles don't matter." | Small changes are exactly where magic numbers and swallowed errors slip in unnoticed. | Principles load before every task — there is no size exception. | | "I know clean code by heart." | The load isn't a reminder for you; it makes the standard active and observable for the task. | Announce and apply on every task, not only when you feel you need it. | | "I'll clean it up in review." | Principles shape code as it's written; review only catches what shaping would have prevented. | They are a mindset during implementation, not a post-hoc checklist. | | "The stack skill already covers quality." | Stack idioms sit on top of the universal foundation — they don't replace it. | Both apply; principles are the foundation. | ## Relationship to Other Capabilities - **Stack skills** (react, flutter, nextjs) add language-specific idioms. Principles provide the universal foundation. - **TDD capability** drives the test-first workflow. Principle 7 guides WHAT to test within that workflow. - **quality-review** (Gate 3) reviews AFTER implementation. Principles guide DURING implementation. Both are needed. - **auto-QA** verifies code against spec. Principles ensure the code is well-crafted regardless of spec compliance. ## Rules - Principles apply to ALL languages. No language-specific rules here. - Principles guide, they don't block. Pragmatic exceptions are fine when explicitly justified. - When principles conflict with project conventions, conventions win (Principle 6). - When principles conflict with each other, clarity wins (Principle 1).