# 05 — Code & deliverable style Naming, comments, structure. Same rules apply whether a human or Claude typed the code. ## Naming - **Files** — lowercase, hyphens for docs (`git-workflow.md`), underscores for Python (`task_runner.py`), kebab for JS/TS where the ecosystem prefers it. Match the surrounding project. - **Functions** — verb phrases. `loadConfig`, not `config`. `runTask`, not `taskRunner`. - **Variables** — say what they are, not their type. `users`, not `userArray`. `retryCount`, not `n`. - **Booleans** — `is*`, `has*`, `should*`. `isReady`, not `ready`. - **Constants** — `UPPER_SNAKE_CASE` only when truly module-level constants. Inside functions, just use a normal `const`. - **No abbreviations** unless they're a domain term. `database`, not `db`. `request`, not `req`. (`req`/`res` in Express handlers is fine — domain convention.) ## Comments Default to none. A comment is justified when **all** are true: - The *why* is non-obvious from the code. - A future reader would otherwise misread the code. - The code itself can't be made clearer (rename, extract, restructure). Don't write: - `// increment counter` next to `counter++` - `// added for the auth refactor` — belongs in the commit message - Block comments restating function signatures - TODOs without an owner or a date — they rot. Either fix it now, file an issue, or delete the comment. Do write: - One-liners explaining a non-obvious workaround, with the *why*. - A `# NOTE:` when behavior would surprise a reader. - Module headers only when a file does something the directory layout doesn't already explain. ## File structure - One concept per file. If you can't summarize the file in one sentence, split it. - Keep tests next to the code, not in a parallel tree, unless the project already does the parallel tree. - Generated files go in `dist/`, `build/`, or similar — and into `.gitignore`. Never edit a generated file. - Lockfiles are checked in. Always. ## Errors - Fail loudly at boundaries (user input, external APIs, file I/O). - Don't `try/except` to silence errors. If you catch, you handle. - Internal functions trust their callers. Don't validate the same input three layers deep. - Logged errors include enough context to debug from logs alone — what was being attempted, which inputs, which path. ## Tests - Test the behavior, not the implementation. If a refactor that preserves behavior breaks a test, the test was wrong. - One assertion per test, ideally. "Tests that test many things at once fail unhelpfully." - Fixtures live next to the tests that use them. - Slow / flaky tests get marked or quarantined, not silently retried. - New code without a test is incomplete unless the project genuinely has no test infrastructure (rare, and a bug in itself). ## READMEs Every repo has a `README.md`. It answers, in order: 1. **What is this?** One paragraph. 2. **How do I run it?** Bash blocks for setup, run, test. 3. **How do I develop on it?** Where the code lives, what the conventions are. 4. **Where does the data come from / go to?** Only if non-obvious. 5. **Pointers.** Related repos, dashboards, docs. Use `templates/README.md.template`. If the README is shorter than the template, that's fine — delete the unused sections. ## Deliverables (task packages, datasets, exports) When we ship a deliverable to a partner or downstream consumer: 1. Versioned filename: `-v.` or `-.`. Pick one convention per project and stick to it. 2. Ships with a `README` describing schema, generation date, known limitations. 3. Ships with a verification report (counts, checksums, sanity checks) in the same archive. 4. Exact commit hash that produced it goes in the README. See `docs/06-handoff.md` for the full checklist. ## What NOT to do - Don't introduce a third way to do something we already do two ways. Pick one and migrate. - Don't add config options "for flexibility" without a real use case. YAGNI. - Don't refactor unrelated code in a feature PR. Open a separate PR. - Don't optimize before measuring. "It might be slow" is not a measurement.