Rules Hub
Coding Rules Library
Rule priority, scope & exceptions
Use this to align rules with the senior-level structure (P0/P1/P2, scope, exceptions/tradeoffs).
Consolidate duplicate/adjacent doc comments left over from a refactor
When renaming or splitting a function, merge any leftover JSDoc block with the new one you add — two consecutive doc blocks above the same declaration duplicate or contradict each other and make the header harder to read.
Bad example
| 1 | /** |
| 2 | * Reads segments from JSON column (not vector database) |
| 3 | * Used for UI display |
| 4 | */ |
| 5 | /** |
| 6 | * Fetch a transcript scoped to its owner and enrich its segments with |
| 7 | * person data. See getTranscriptForUser for scoping semantics. |
| 8 | */ |
| 9 | static async getTranscriptWithSegmentsForUser(transcriptId: number, userId: number) { /* ... */ } |
Explanation (EN)
The old doc block (about JSON-column segments) was left in place when the function was renamed and a new doc block was added above it. Two stacked JSDoc comments on one declaration read as contradictory or redundant, and it's unclear which one is still accurate.
Objašnjenje (HR)
Stari blok dokumentacije (o segmentima iz JSON stupca) ostavljen je nakon sto je funkcija preimenovana i dodan novi blok dokumentacije iznad njega. Dva naslagana JSDoc komentara na jednoj deklaraciji citaju se kao proturjecni ili suvisni, i nejasno je koji je jos uvijek tocan.
Good example
| 1 | /** |
| 2 | * Fetch a transcript scoped to its owner and enrich its segments with |
| 3 | * person data (reads segments from the JSON column, not the vector |
| 4 | * database). See getTranscriptForUser for scoping semantics. |
| 5 | */ |
| 6 | static async getTranscriptWithSegmentsForUser(transcriptId: number, userId: number) { /* ... */ } |
Explanation (EN)
Merging into a single doc block keeps the still-relevant detail (JSON column vs vector DB) while presenting one coherent description of the function.
Objašnjenje (HR)
Spajanje u jedan blok dokumentacije zadrzava jos uvijek relevantan detalj (JSON stupac vs vektorska baza) uz prezentiranje jednog koherentnog opisa funkcije.