code-quality-standards

Readability

• Max 120 character line width.
• Prefer explicit code over clever tricks — if it needs a comment to explain what it does, rewrite it.
• No abbreviations in public API names (context not ctx, repository not repo).
• Keep functions short and focused on a single responsibility.

Complexity limits

Max 20 cyclomatic complexity per function, max 4 levels of nesting depth, max 50 lines per function. Use early returns to flatten conditionals. Break complex functions into well-named helpers that each do one thing.

Anti-patterns

• No magic numbers — use named constants.
• No global state — use dependency injection.
• No inheritance for code reuse — prefer composition.
• No bare exception handlers — catch specific types.
• No mocking internal services — use real objects for integration tests.
• No blocking I/O in async code paths — keep async paths fully async.

Duplication

Extract shared logic after the third repetition, not before. Three similar lines are better than a premature abstraction. When extracting, ensure the shared code has a single reason to change — if two callers would evolve the logic differently, keep them separate. Premature abstraction creates worse coupling than duplication.

Dead code

Remove dead code instead of commenting it out. Version control preserves history; commented-out code creates confusion and maintenance burden.

Suppressions

Fix the cause instead of suppressing a lint rule, type error or test. A necessary suppression (lint-disable, noqa, ts-ignore, #[allow]) is scoped to the narrowest line, names the rule, and gives a one-line reason. Never update a snapshot or baseline just to hide a failure.

Markers

TODO, FIXME, HACK and XXX take the form TODO(PROJ-123): description. The key is an existing open tracker issue for future work, never the issue of the current change (it closes on merge). No bare markers, owners or dates.