Rules Hub
Coding Rules Library
← Back to all rules
Rule priority, scope & exceptions
Use this to align rules with the senior-level structure (P0/P1/P2, scope, exceptions/tradeoffs).
fullstack ruleP2universalStack: typescript
documentationclean-codemaintainability
Keep JSDoc @returns in sync with the actual return type
Update doc comments when signatures change so @returns/@param describe the real types, not stale ones.
PR: startsiden/hegnar-quartr-ws#5Created: Jun 17, 2026
Bad example
Old codets
| 1 | /** |
| 2 | * @returns A promise that resolves to an array of Instrument objects. |
| 3 | */ |
| 4 | private async getInstrumentMap(ids: number[]): Promise<Map<number, Instrument> | null> { /* ... */ } |
Explanation (EN)
The doc promises an array while the method returns a Map-or-null, so anyone reading the comment is actively misled.
Objašnjenje (HR)
Dokumentacija obećava niz, a metoda vraća Map-ili-null, pa je svatko tko čita komentar aktivno doveden u zabludu.
Good example
New codets
| 1 | /** |
| 2 | * @returns A promise resolving to a Map of id to Instrument, or null if none found. |
| 3 | */ |
| 4 | private async getInstrumentMap(ids: number[]): Promise<Map<number, Instrument> | null> { /* ... */ } |
Explanation (EN)
The comment now matches the signature, so it documents rather than misinforms.
Objašnjenje (HR)
Komentar sada odgovara potpisu, pa dokumentira umjesto da dezinformira.