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).
Avoid comments explaining self-evident language features
Don't add comments explaining well-known language idioms like type-only imports; they add noise, not clarity.
Bad example
| 1 | // Type-only: a value import here would pin the ~150 KB library into the bundle |
| 2 | // and undo the dynamic import in ChartGraph. |
| 3 | import type { ChartOptions } from 'heavy-charting-lib'; |
Explanation (EN)
This comment explains a well-known TypeScript idiom (`import type` avoids a runtime/bundle dependency) that any developer on the team already understands, adding noise instead of value.
Objašnjenje (HR)
Ovaj komentar objašnjava dobro poznat TypeScript idiom (`import type` izbjegava runtime/bundle ovisnost) koji svaki developer u timu već razumije, pa samo dodaje šum umjesto vrijednosti.
Good example
| 1 | import type { ChartOptions } from 'heavy-charting-lib'; |
Explanation (EN)
The import speaks for itself — no comment needed to explain what a type-only import does.
Objašnjenje (HR)
Import govori sam za sebe — nije potreban komentar koji objašnjava što radi type-only import.
Notes (EN)
If a piece of syntax is a common, well-understood idiom in the language/ecosystem the team works in, don't annotate it with an explanation. Reserve comments for genuinely non-obvious 'why' (e.g. a workaround for a specific bug, a business rule), not for restating what any experienced developer already knows.
Bilješke (HR)
Ako je neka sintaksa uobičajeni, dobro poznat idiom u jeziku/ekosustavu s kojim tim radi, nemoj je popratiti objašnjenjem. Komentare ostavi za stvarno nejasan 'zašto' (npr. workaround za specifičan bug, poslovno pravilo), a ne za ponavljanje onoga što svaki iskusan developer već zna.
Exceptions / Tradeoffs (EN)
Fine to add a short comment if the type-only import exists specifically to preserve a non-obvious optimization (e.g. keeping a heavy library out of a particular bundle) that isn't visible from the import alone — but keep it to the non-obvious part, not a definition of what 'import type' does.
Iznimke / Tradeoffi (HR)
U redu je dodati kratak komentar ako type-only import postoji baš zato da sačuva neku ne-očitu optimizaciju (npr. da teška biblioteka ne uđe u određeni bundle) koja se ne vidi iz samog importa — ali neka komentar pokriva samo taj ne-očiti dio, a ne objašnjava što `import type` uopće radi.