General Principles
This section describes the fundamental guidelines that underpin the concrete rules throughout the rest of this document. When a specific rule is missing or ambiguous, developers should use these principles to make a decision.
Readability First
Code is read far more often than it is written. Always write code for the next person who will maintain it, not for the compiler. Favor clarity over cleverness.
Consistency (Uniformity)
Consistency across files, services, and teams reduces the mental effort required to understand and modify code. Once a pattern is established in a codebase, follow it unless there is a compelling reason to change it. The rules in this document are the baseline for consistency.
DRY (Don’t Repeat Yourself)
Avoid duplicating logic or configuration. Extract reusable code into shared libraries, services, or utility functions. However, do not over-engineer: a little duplication is better than a wrong abstraction.
KISS (Keep It Simple, Stupid)
Write simple, straightforward solutions. Do not introduce complex design patterns or abstractions unless they solve a real, present problem. Complexity should be justified and documented.
SOLID Principles
Strive to adhere to the SOLID principles of object-oriented design, adapted to the appropriate paradigm (C#, TypeScript, etc.):
Single Responsibility: a component, class, or function should have one reason to change.
Open/Closed: open for extension, closed for modification.
Liskov Substitution: subclasses should be substitutable for their base classes.
Interface Segregation: many specific interfaces are better than one general-purpose interface.
Dependency Inversion: depend on abstractions, not on concretions.
Explicit Over Implicit
Make behavior obvious. Do not rely on hidden conventions, magical configurations, or implicit type coercion. Choose expressive variable names, explicit typings, and clear error messages.
Version Control Over Dead Code
Do not leave commented-out code in the codebase. If you remove functionality, delete it; the version control system retains the history. If a temporary workaround is needed, mark it clearly with a TODO and a reference to the Jira ticket.
YAGNI (You Aren’t Gonna Need It)
Do not add functionality, abstractions, or configuration "just in case". Build only what is necessary for the current requirements. Future-proofing without a concrete roadmap leads to unnecessary complexity and maintenance burden.
Collective Ownership
Every team member is responsible for code quality across the entire project. Anyone can and should suggest improvements, fix violations, and update this document when needed.