Engineering Guidelines
Welcome — this is our shared playbook for building great software at Finperiti, written by engineers, for engineers. Each topic is a set of clear, practical directives, chosen to teach good judgement rather than just hand down rules. Use the menu to explore.
If you read only one page, make it Zero Tolerance. It's the most important page on this site and where everyone should start — the absolute, non-negotiable rules we never break, no matter what.
Think of the rest as a first draft, not the final word. These guidelines are a living document — they're meant to grow and change as we discover better ways of working, learn from what goes wrong, and fold in good ideas from across the team. The best version of this site is one that everyone helps shape, so please don't treat anything here as set in stone.
Found a mistake, disagree with a call, or want to suggest a change? Please reach out to Gordon — every bit of feedback is genuinely welcome, no matter how small. Editing is a little manual for now, but I'll make it much easier to contribute soon. This is just the beginning, and I'm looking forward to building it together. 🚀
How to read the commands
Every rule is tagged with a command. They differ by strength: two are absolute (Always, Never), two are strong defaults that allow judgement (Do, Do not), and two are softer steers to weigh (Consider, Avoid).
| Always | A hard requirement — every time, no exceptions. The non-negotiable positive. Many Always rules are also conditions of working here. e.g. Always validate a token's signature, issuer, audience, and expiry before trusting any claim. |
| Do | The recommended default — the right way in normal cases. Follow it unless you have a specific, defensible reason not to. Weaker than Always: it expects judgement, not blind compliance. e.g. Do handle an error only at a level that can make a meaningful decision about it. |
| Consider | A judgement call worth weighing — not always required. A good idea to evaluate for your situation; sometimes it won't apply. e.g. Consider separating transient failures (retry) from permanent ones (fail fast). |
| Avoid | The soft negative — steer away from this; there's usually a better option. The mirror of Consider: discouraged, but legitimate in specific, justified cases. Weaker than Do not. e.g. Avoid random GUID / UUIDv4 values as clustered primary keys — prefer sequential UUIDv7. |
| Do not | An anti-pattern to avoid as the default. The firm negative mirror of Do — rare exceptions need a clear justification. Bad, but not by itself catastrophic. e.g. Do not catch broad exceptions in low-level helpers just to "be safe". |
| Never | An absolute prohibition — no exceptions, ever, for any reason. The negative mirror of Always. These are the most serious rules; many are Zero Tolerance and breaking one can be a disciplinary matter. e.g. Never log secrets, credentials, tokens, or full PII. |
In short: Always/Never are mandatory and admit no exceptions; Do/Do not are strong defaults that allow reasoned exceptions; Consider/Avoid are softer steers to weigh. Ask chips, where present, are self-review questions rather than directives.
The general topics come first. The Coding Standards section at the bottom holds our language and framework conventions, plus the specific traps we've actually hit in C#/.NET, React, and SQL.