55 lines
2.2 KiB
Plaintext
55 lines
2.2 KiB
Plaintext
---
|
||
description: Documentation standards for backend TypeScript code (JSDoc comments)
|
||
globs: backend/src/**/*.ts
|
||
alwaysApply: false
|
||
---
|
||
|
||
# Backend documentation conventions
|
||
|
||
Every new or modified backend file must include clear JSDoc comments so maintenance stays easy (Spring Boot–style readability).
|
||
|
||
## Required comments
|
||
|
||
1. **File / module** — One block at the top describing the layer and responsibility:
|
||
- `models/` → entity mapped to a DB table
|
||
- `dto/` → API/query projection (not a full entity)
|
||
- `repositories/` → data access (SQL)
|
||
- `services/` → business logic
|
||
- `controllers/` → HTTP handlers (thin; delegate to services)
|
||
- `middleware/` → Express pipeline hooks
|
||
|
||
## Layer dependencies (Spring Boot style)
|
||
|
||
- **Controller → Service only** — never import repositories or run SQL in controllers.
|
||
- **Service → Repository (+ other services when needed)** — business logic, decryption, orchestration.
|
||
- **Repository → Models / DTO row types** — SQL and data mapping only; no HTTP concerns.
|
||
- **Exceptions kept as-is** when justified: background jobs (`depositMonitorService`), `authService` reading `settingsRepository` directly for token policy, `middleware` calling `authService.verifyToken`.
|
||
|
||
2. **Every exported function** — JSDoc with:
|
||
- What it does (one sentence)
|
||
- `@param` for non-obvious parameters
|
||
- `@returns` when the return value is not obvious
|
||
- `@throws` when the function throws domain errors
|
||
|
||
3. **Non-exported helpers** — Comment when logic is non-obvious (crypto, blockchain, ledger locking, etc.).
|
||
|
||
4. **Interfaces / types in models & dto** — Brief description of what they represent and which table/view they map to.
|
||
|
||
## Style
|
||
|
||
- Write comments in **English** (matches existing codebase).
|
||
- Prefer **why** over **what** when the code is self-explanatory.
|
||
- Do not restate obvious one-liners (`return rows[0] || null` needs no comment).
|
||
- Keep comments up to date when changing behavior.
|
||
|
||
## Example
|
||
|
||
```typescript
|
||
/**
|
||
* Finds a user by email hash (used for login and uniqueness checks).
|
||
* @param emailHash SHA-256 hash of normalized email
|
||
* @returns User row or null if not found
|
||
*/
|
||
export async function findByEmailHash(emailHash: string): Promise<User | null> {
|
||
```
|