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