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).
Keep doc comments accurate to the function's real behavior
Doc comments must describe what the code actually does, including all branches; update them whenever behavior changes.
Bad example
| 1 | /** |
| 2 | * Returns the currently live call if available, otherwise returns the most recent past call. |
| 3 | */ |
| 4 | async function getLatestCall(id: string): Promise<Call | null> { |
| 5 | // next represents the next upcoming OR currently live call |
| 6 | const next = await getNextOrLiveCall(id); |
| 7 | if (next) return next; |
| 8 | return getMostRecentPastCall(id); |
| 9 | } |
Explanation (EN)
The comment only mentions the 'currently live' case, but the function also returns the next upcoming call. A reader trusting the comment would assume scheduled calls are excluded, which is wrong.
Objašnjenje (HR)
Komentar spominje samo slučaj 'trenutno uživo', ali funkcija vraća i sljedeći nadolazeći poziv. Čitatelj koji vjeruje komentaru pretpostavio bi da su zakazani pozivi izostavljeni, što je netočno.
Good example
| 1 | /** |
| 2 | * Returns the next upcoming or currently live call if available, |
| 3 | * otherwise returns the most recent past call. |
| 4 | */ |
| 5 | async function getLatestCall(id: string): Promise<Call | null> { |
| 6 | const next = await getNextOrLiveCall(id); |
| 7 | if (next) return next; |
| 8 | return getMostRecentPastCall(id); |
| 9 | } |
Explanation (EN)
The comment now covers every branch the function actually takes, so it cannot mislead a reader about whether upcoming calls are returned.
Objašnjenje (HR)
Komentar sada pokriva svaku granu koju funkcija stvarno izvršava, pa ne može zavarati čitatelja oko toga vraćaju li se nadolazeći pozivi.
Notes (EN)
When you fix a bug or change behavior, scan the surrounding doc comments and update them in the same change.
Bilješke (HR)
Kad ispraviš bug ili promijeniš ponašanje, pregledaj okolne doc komentare i ažuriraj ih u istoj promjeni.