Writing Self-Documenting TypeScript: Naming, Narrowing, and Knowing When to Stop

There's a quiet kind of technical debt that doesn't show up in bundle size or test coverage: code that requires a mental simulation to understand. You read it line by line, holding context in your head, reverse-engineering what the author meant. It works — but it explains nothing. TypeScript gives you unusually powerful tools to fight this. Not just for catching bugs, but for communicating intent. This post is about using those tools deliberately in UI projects — the kind with complex state, conditional rendering, and types that evolve fast. 1. Name Types Like You're Writing Documentation The first place self-documenting code lives is in your type names. A good type name answers what this thing is, not just what shape it has. Avoid: type Obj = { id: string; val: string | null; active: boolean; }; Prefer: type FilterOption = { id: string; label: string | null; isSelected: boolean; }; The second version tells a reader — immediately, before any implementation — that this is a filter optio