TypeScript Style Rules

Rules are ordered by how much damage breaking them does. Each one names the failure it prevents, because a rule without a reason gets discarded the first time it is inconvenient.

Types must be honest

1. Never use any to silence an error. If the type is genuinely unknown, use unknown and narrow it. any does not fix the problem, it hides it until runtime.
2. Never use a non-null assertion (!) to silence an error. Either the value can be null and you must handle it, or it cannot and the type is wrong. Fix the type.
3. A function's return type must describe every path. If it can return undefined, say so. A signature that lies is worse than no signature.
4. Do not widen a type to make a call site compile. Narrow at the boundary instead.
5. Parse external data, do not cast it. Anything from a network, a file, or a database is unknown until validated. A cast on untrusted input is a runtime crash waiting for the right payload.

Errors

6. Never write an empty catch. If a failure is genuinely ignorable, say why in a comment. An unexplained empty catch is indistinguishable from a bug.
7. Catch narrowly. Wrap the call that can fail, not the whole function body.
8. Do not convert an error into a falsy return value unless every caller checks it. Silent failure propagates further than a throw.
9. Preserve the cause. When rethrowing, use { cause: err } rather than dropping the original and its stack.

Structure

10. Do not create an abstraction for one caller. Two callers is a coincidence, three is a pattern. The premature interface costs more than the duplication.
11. Do not add a config option nobody asked for. Every option is a branch that must be tested and a decision the reader must understand.
12. Keep the module boundary narrow. Export what callers need. An exported internal becomes someone's dependency the moment it is visible.
13. Match the file you are editing. Its naming, its error style, its import order. Consistency inside a file beats your preference.

Async

14. Never leave a promise unawaited unless you deliberately want fire-and-forget, in which case attach a catch and say so in a comment.
15. Do not use Promise.all where one failure should not cancel the rest. Use allSettled and handle each result.
16. Do not await in a loop when the calls are independent. Collect the promises and await once.

Comments

17. Comment the why, never the what. The code says what it does. Explain the constraint, the workaround, the reason for the surprising choice.
18. Do not narrate a change. // changed to fix bug is noise the moment it lands. That belongs in the commit message.
19. Delete commented-out code. Version control already has it.

What good looks like

// The upstream API returns 200 with an error body when the key is expired,
// so a status check alone is not enough here.
const parsed = ResponseSchema.safeParse(await res.json());
if (!parsed.success) {
  throw new Error(`malformed response from ${url}`, { cause: parsed.error });
}

Honest types, narrow catch, external data parsed, and a comment that explains a thing the reader could not have guessed.