// General coding-style rules to apply to every project. Use when writing or editing source code, comments, or doc comments — especially when adding new files or refactoring.
| name | dev-rules |
| description | General coding-style rules to apply to every project. Use when writing or editing source code, comments, or doc comments — especially when adding new files or refactoring. |
These are user-wide style rules. Apply them everywhere unless a project's own CLAUDE.md explicitly overrides one of them.
Do not write decorative section banners. Examples of what NOT to do:
// ----- top-level convenience re-exports -----------------------------------------
// =============== HELPERS ===============
// /////////////// Server entry points ///////////////
// --- Database setup ---
// ===== INTERNAL HELPERS =====
These add visual noise, make diffs ugly, and rot when code moves. If a section is large enough that a header feels useful, that is a signal to split the file or move items into a submodule instead of papering over it with a banner.
If a logical grouping inside one file truly helps the reader, use a single-line plain comment with a short noun phrase (no dashes, equals signs, slashes, or trailing fillers):
// re-exports from tako-core
pub use tako_core::body;
pub use tako_core::types;
Skip comments that just paraphrase the next line. Code with good names doesn't need narration.
// BAD — restates the code
// Increment counter
counter += 1;
// BAD — narrates structure that's obvious from the AST
// Loop through users
for user in users { ... }
A comment earns its place only when it explains the why that isn't visible: a hidden constraint, a workaround, an invariant, a surprising performance choice.
Don't reference tasks, PRs, callers, or migration history in comments. That belongs in commit messages and PR descriptions, where it stays attached to the diff and doesn't rot.
// BAD
// added for the new auth flow (PR #482)
// used by the worker pool refactor
// removed once compio 0.18 ships
// OK if the rationale itself is durable
// SO_REUSEPORT distributes accepts at the kernel level — required for
// thread-per-core to avoid contending on a single accept queue.
A one-line summary plus an example is enough for 95% of public items. Walls of doc text get skimmed and outdated. If something needs paragraphs of warnings, the API design is probably wrong.
// TODO / // FIXME markersOnly leave a TODO if there is a concrete next action. Vague TODOs ("// TODO: improve this") get ignored forever. If there is no clear next step, delete the comment and just write the code.
Prefer no comment over a marginal one. Reviewers can ask if something is unclear; deleting noise improves signal.