ai-agents code-quality.instructions.md

Code Quality

This rule sets the baseline quality standard for all code you write or change. It merges the everyday fundamentals from Robert Martin's Clean Code and Steve McConnell's Code Complete. Apply these rules on every edit. They override stylistic preferences but defer to project conventions found in AGENTS.md, .editorconfig, and .markdownlint-cli2.yaml.

Naming

Names are documentation. A reader who knows nothing about the change should understand the code from the names alone.

• Choose intention-revealing names. daysSinceLastLogin beats d or delta. isExpired beats flag.
• Use pronounceable, searchable names. customerCount beats cc.
• Drop abbreviations and Hungarian prefixes. userList beats usrLst or lstUsr.
• Use one word per concept across the whole codebase. Pick fetch, get, or retrieve and stay with it.
• Names track scope. Short names fit short scopes. Long names fit long-lived classes and public APIs.
• Class names are nouns. Method names are verbs. Boolean methods read as predicates: isReady, hasChildren, canCommit.
• Avoid disinformation. Do not call something accountList if it is a Set. Do not name a boolean status.
• Mirror the domain. If the team says "tenant," do not write customer in code. Ubiquitous language reduces translation cost.

When you find yourself writing a comment to explain a name, rename instead.

Functions

Functions are the core unit of design. Keep them small, single-purpose, and easy to test.

• Functions should do one thing. If you can describe the function as "X and Y," split it.
• Prefer 20 lines or fewer. The project ceiling is 60. Past that, extract.
• Aim for cyclomatic complexity of 10 or lower. Past that, extract or use table-driven logic.
• Limit parameters to three. Prefer two. Zero is best. Bundle related parameters into a parameter object.
• Avoid flag arguments. A boolean argument means the function does two things. Split it into renderTextual() and renderHtml().
• Output parameters are confusing. Return a value, a tuple, or a small record.
• One level of abstraction per function. A high-level orchestrator should not parse strings; a parser should not log analytics.
• Apply the Stepdown Rule. Read top to bottom: each function calls the next level of detail.
• No side effects beyond the function's name. validatePassword(user) should not also log the user in.