Clean Code

Clean Code

Favor code that is easy to understand, easy to change, and hard to misuse.

Core Principles

1. Keep functions small and focused on one job.
2. Prefer clear, specific names for variables, functions, types, and files.
3. Avoid duplication when the duplicated logic represents the same concept.
4. Keep each file centered on one clear responsibility.
5. Choose straightforward control flow over cleverness.
6. Apply these rules with judgment; do not over-abstract or split code prematurely.

Naming

• Prefer names that reveal intent, not implementation trivia.
• Use domain language when available instead of generic names like data, item, helper, utils, or handleStuff.
• Make boolean names read like facts or predicates.
• Rename unclear symbols when touching code rather than working around bad names.

Functions

• Keep functions short enough to understand in one pass.
• Give each function one main responsibility.
• If a function mixes parsing, validation, transformation, side effects, and rendering, split it.
• Prefer passing clear inputs and returning clear outputs over mutating hidden state.
• Extract helpers only when they create clarity or remove meaningful duplication.

DRY

• Remove repeated logic, repeated condition trees, and repeated data shaping when they describe the same rule.
• Do not force abstraction for coincidental similarity.
• If duplication is small and keeps code local and obvious, it can be acceptable.
• If the same behavior changes in multiple places, centralize it.

File Boundaries

• Keep each file focused on one component, module, workflow, or concept.
• Split files that mix unrelated responsibilities.
• Avoid dumping unrelated helpers into catch-all files.
• Prefer colocating tightly related code, but separate code when file size or mixed concerns hurt comprehension.

Refactoring Workflow

1. Identify the main source of complexity: duplication, naming, function size, mixed responsibilities, or unclear file boundaries.
2. Make the smallest structural changes that improve clarity.
3. Rename first when naming is the main issue.
4. Extract functions or modules when distinct responsibilities emerge.
5. Re-check whether the result is actually simpler, not just more abstract.

Pragmatic Exceptions

• Do not create layers, wrappers, or abstractions without a clear payoff.
• Do not split code so aggressively that understanding requires jumping through too many files.
• Favor local clarity over theoretical purity.
• Preserve existing patterns when they are already clear and consistent.

Review Guidance

When reviewing or editing code:

• Prefer concrete improvements over broad style commentary.
• Flag long functions, vague names, duplicated business rules, and mixed-purpose files.
• Suggest the simplest refactor that materially improves readability or maintainability.
• If a cleanup is out of scope, note it briefly instead of expanding the task unnecessarily.

Examples

• "Refactor this module to be easier to maintain."
• "Implement this feature, but keep the code clean and modular."
• "Review this file for naming and single-responsibility issues."
• "Reduce duplication in this logic without overengineering it."