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

4.1 KiB

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.