AzuTear
217 lines
6.2 KiB
Markdown
217 lines
6.2 KiB
Markdown
# Conventions
|
|
|
|
This document defines project engineering standards. It should remain practical,
|
|
specific, and enforceable.
|
|
|
|
For project facts, see [PROJECT.md](PROJECT.md).
|
|
For architecture boundaries, see [ARCHITECTURE.md](ARCHITECTURE.md).
|
|
For task quality gates, see [CHECKLISTS.md](CHECKLISTS.md).
|
|
|
|
## Naming
|
|
|
|
Use names that expose intent and domain meaning.
|
|
|
|
- Prefer domain terms over technical shorthand.
|
|
- Avoid abbreviations unless they are widely understood in the project.
|
|
- Name booleans as predicates, such as `isEnabled`, `hasPermission`, or
|
|
`canRetry`.
|
|
- Name commands by action and object, such as `CreateInvoice` or
|
|
`syncCustomer`.
|
|
- Name events in past tense when they represent something that happened.
|
|
|
|
Add language-specific naming rules here:
|
|
|
|
- `{{LANGUAGE_NAMING_RULE}}`
|
|
|
|
## File Organization
|
|
|
|
Files should have one clear responsibility.
|
|
|
|
- Keep files small enough to review comfortably.
|
|
- Co-locate tests with the tested module when that matches the stack convention.
|
|
- Separate generated files from hand-written source.
|
|
- Avoid catch-all utility files that collect unrelated behavior.
|
|
|
|
Project-specific rules:
|
|
|
|
- `{{FILE_ORGANIZATION_RULE}}`
|
|
|
|
## Folder Organization
|
|
|
|
Folders should communicate ownership and architecture boundaries.
|
|
|
|
- Organize by feature or module when domain ownership matters.
|
|
- Organize by technical layer only when it improves clarity for the project.
|
|
- Keep public interfaces easy to find.
|
|
- Keep infrastructure details out of domain folders unless deliberately chosen.
|
|
|
|
Project-specific folder map:
|
|
|
|
| Folder | Rule |
|
|
| --- | --- |
|
|
| `{{FOLDER}}` | `{{FOLDER_RULE}}` |
|
|
|
|
## Dependency Injection
|
|
|
|
Use dependency injection to make boundaries explicit and tests practical.
|
|
|
|
- Inject external resources, clocks, random generators, HTTP clients, file
|
|
systems, queues, and database access.
|
|
- Avoid service locators unless the framework requires them.
|
|
- Keep object lifetimes explicit.
|
|
- Do not inject dependencies that are pure values or local implementation
|
|
details.
|
|
|
|
Project-specific DI rules:
|
|
|
|
- `{{DEPENDENCY_INJECTION_RULE}}`
|
|
|
|
## Logging
|
|
|
|
Logging should support operations and debugging without leaking sensitive data.
|
|
|
|
- Use structured logs when the platform supports them.
|
|
- Include correlation or request identifiers.
|
|
- Log decisions and external failures at meaningful boundaries.
|
|
- Do not log secrets, access tokens, passwords, private keys, or full payment
|
|
data.
|
|
- Avoid noisy logs inside tight loops or high-volume paths.
|
|
|
|
Project-specific logging rules:
|
|
|
|
- `{{LOGGING_RULE}}`
|
|
|
|
## Validation
|
|
|
|
Validation should happen at the correct boundary.
|
|
|
|
- Validate transport shape at the interface boundary.
|
|
- Validate business invariants in the domain or application layer.
|
|
- Validate persistence constraints before relying on database failures for
|
|
expected user errors.
|
|
- Return actionable validation feedback where appropriate.
|
|
|
|
Project-specific validation rules:
|
|
|
|
- `{{VALIDATION_RULE}}`
|
|
|
|
## Error Handling
|
|
|
|
Errors should be explicit, observable, and safe.
|
|
|
|
- Use typed or structured errors where the language supports them.
|
|
- Do not swallow exceptions without a recovery path.
|
|
- Map internal errors to stable user-facing or client-facing responses.
|
|
- Preserve diagnostic context for logs.
|
|
- Avoid exposing stack traces or implementation details to users.
|
|
|
|
Project-specific error rules:
|
|
|
|
- `{{ERROR_HANDLING_RULE}}`
|
|
|
|
## DTO Rules
|
|
|
|
DTOs represent boundary contracts.
|
|
|
|
- Keep DTOs separate from domain models when they change for different reasons.
|
|
- Do not put business rules in DTOs.
|
|
- Version public contracts deliberately.
|
|
- Validate DTO shape before mapping to domain commands or queries.
|
|
- Avoid leaking persistence models through public APIs.
|
|
|
|
Project-specific DTO rules:
|
|
|
|
- `{{DTO_RULE}}`
|
|
|
|
## Repository Rules
|
|
|
|
Use the repository pattern as the default persistence boundary.
|
|
|
|
Repositories, gateways, or data access abstractions should express domain
|
|
persistence intent without hiding important consistency behavior.
|
|
|
|
- Define repository interfaces at the application or domain boundary.
|
|
- Implement repositories in infrastructure or persistence-specific modules.
|
|
- Prefer specific repositories such as `OrderRepository` or
|
|
`SupportRequestRepository`.
|
|
- Keep query methods specific enough to reveal purpose.
|
|
- Avoid generic repositories when they obscure domain behavior.
|
|
- Document transaction boundaries.
|
|
- Make idempotency explicit for write operations where retries are possible.
|
|
|
|
Project-specific repository rules:
|
|
|
|
- `{{REPOSITORY_RULE}}`
|
|
|
|
## Service Rules
|
|
|
|
Services should coordinate use cases, not become unbounded containers.
|
|
|
|
- Prefer cohesive application services around use cases.
|
|
- Keep domain rules in domain objects or domain services.
|
|
- Keep infrastructure calls behind clear interfaces.
|
|
- Avoid services named only after technical actions such as `Manager`,
|
|
`Helper`, or `Processor` unless the meaning is precise in context.
|
|
|
|
Project-specific service rules:
|
|
|
|
- `{{SERVICE_RULE}}`
|
|
|
|
## Testing
|
|
|
|
Tests should match risk and behavior.
|
|
|
|
- Unit test domain logic and pure transformations.
|
|
- Integration test database, queue, file, network, and framework boundaries.
|
|
- End-to-end test critical user journeys.
|
|
- Regression test bugs before or with the fix.
|
|
- Keep tests deterministic and independent where practical.
|
|
|
|
Project-specific testing rules:
|
|
|
|
- `{{TESTING_RULE}}`
|
|
|
|
## Git Workflow
|
|
|
|
Use [branching.md](branching.md) for branch strategy.
|
|
|
|
Default expectations:
|
|
|
|
- Keep commits focused and reviewable.
|
|
- Write commit messages that describe the reason and outcome.
|
|
- Rebase or merge according to the project branch policy.
|
|
- Do not mix unrelated refactors with behavior changes.
|
|
|
|
## Pull Requests
|
|
|
|
Pull requests should explain what changed, why it changed, and how it was
|
|
validated.
|
|
|
|
Recommended PR sections:
|
|
|
|
- Summary.
|
|
- Scope.
|
|
- Validation.
|
|
- Risks.
|
|
- Screenshots or recordings for UI changes.
|
|
- Migration or deployment notes when relevant.
|
|
|
|
Use [CHECKLISTS.md](CHECKLISTS.md) before requesting review.
|
|
|
|
## Code Reviews
|
|
|
|
Reviews should prioritize correctness and maintainability.
|
|
|
|
Review for:
|
|
|
|
- Behavior and edge cases.
|
|
- Security and authorization.
|
|
- Data integrity.
|
|
- Architecture boundaries.
|
|
- Test quality.
|
|
- Operational impact.
|
|
- Readability.
|
|
|
|
Style comments should reference documented conventions or automated tooling
|
|
where possible.
|