Files
praxis/docs/05-code-style.md
T
阿白叔andClaude Opus 4.7 7f9ca07903 init: scaffold team-guide v0.1
Working agreements for our 1-3 person AI-assisted team. Six docs
(vibe coding, Claude Code, git workflow, skills/planning, code style,
handoff) plus four templates (CLAUDE.md, README, PR description,
handoff checklist).

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
2026-05-20 09:02:21 +08:00

112 lines
4.1 KiB
Markdown

# 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: `<name>-v<n>.<ext>` or `<name>-<YYYYMMDD>.<ext>`.
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.