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 maintainer warnings out of public API documentation
An instruction addressed to your own team is not useful to the consumers who read a published API description, and repeating it in the docs plus the constants plus the type is three copies to keep in sync. Put the consumer-facing facts in the API docs and the warning in the code.
Bad example
| 1 | @ApiOperation({ |
| 2 | description: |
| 3 | "Returns the daily winners. Consumed by the display feed. " + |
| 4 | "Do not point it at the widget DTO.", // instruction to us, on a public surface |
| 5 | }) |
Explanation (EN)
Consumers read an internal maintenance note they cannot act on, and the same warning already exists in two other places.
Objašnjenje (HR)
Potrosaci citaju internu biljesku o odrzavanju na koju ne mogu djelovati, a isto upozorenje vec postoji na dva druga mjesta.
Good example
| 1 | // Serialised by its own frozen DTO - do not point this at the widget DTO. |
| 2 | @ApiOperation({ |
| 3 | description: |
| 4 | "Returns the daily winners and the last updated time. Consumed by the display feed, which renders it in players we do not own, so the response shape is frozen.", |
| 5 | }) |
Explanation (EN)
The published description tells consumers what they need; the maintainer warning lives once, next to the code it constrains.
Objašnjenje (HR)
Objavljeni opis govori potrosacima ono sto im treba, a upozorenje za odrzavatelje stoji jednom, uz kod koji ogranicava.
Notes (EN)
Also check that the description matches what the code does. A published line claiming a resize that no parameter performs is what makes someone later restore the parameter and break the contract.
Bilješke (HR)
Provjeri i podudara li se opis s onim sto kod radi. Objavljena tvrdnja o promjeni velicine koju nijedan parametar ne izvodi navest ce nekoga da kasnije vrati taj parametar i pokvari ugovor.