Engineering Guidelines
A short, timeless standard for how we build software here. Each topic is a set of clear directives — chosen to teach judgement, not just rules. Use the menu to navigate.
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.