Documenting Known Type Gaps
You'll learn: How adding a comment with any transforms it from a mistake into a documented choice.
When you use any, TypeScript can't tell whether you intended to opt out of type safety or simply forgot to add proper types. This ambiguity creates confusion for future developers (including yourself).
The solution: Always pair any with an explanatory comment.
The Signal of Intent
Think of any like a warning sign on a construction site. An unmarked hole in the ground is dangerous—someone might fall in without knowing why it exists. But a hole with a sign saying "Foundation work in progress—safe path to the right" tells people it's intentional and gives them guidance.
Similarly, // TODO: type this properly or // any because third-party lib has no types tells readers this isn't carelessness—it's a deliberate, documented gap.
What to Document
When using any, explain:
- Why: "No types available for legacy API"
- What's the plan: "Will add types after v2 migration"
- Alternatives considered: "Tried unknown but requires too many guards for prototype"
This creates a paper trail. During code reviews, commented any shows you've thought through the trade-off. During refactoring, these comments become a to-do list of type gaps to close.
The Difference It Makes
// Without documentation - looks like laziness:
let data: any;
// With documentation - shows deliberate choice:
// any: Response shape changes based on endpoint called
// TODO: Create discriminated union after API stabilizes
let data: any;
Key Takeaway: A commented any signals "known type gap" rather than "forgotten types"—it transforms a liability into documented technical debt.