Course contentsShow
← TypeScript
Lesson 900 of 1,79620. The any Escape HatchFree lesson

Documenting Why You Suppress

Always adding explanatory comments alongside suppressions to explain the reason and expected resolution.

Documenting Why You Suppress

What you'll learn: How to add explanatory comments alongside type suppressions to explain the reason and expected resolution.

The Practice of Responsible Suppression

Using @ts-expect-error or @ts-ignore is sometimes necessary, but dropping one of these comments into your code without explanation is like leaving a cryptic note for your future self. You've just bypassed TypeScript's safety net—the least you can do is explain why and what happens next.

Think of suppression comments as IOU notes in your codebase. If you borrow against type safety, you should document the debt: what you're suppressing, why it's necessary right now, and how you plan to pay it back later.

Why Documentation Matters

When someone (including future you) encounters a suppression, they need answers to three questions:

  1. What's being suppressed? What type error are we ignoring?
  2. Why is this necessary? Is it a library bug? A migration step? Technical debt?
  3. What's the resolution path? Will we fix this? When? How?

Without this context, suppressions become mysteries. Are they still needed? Were they temporary workarounds that became permanent? Nobody knows, so nobody dares remove them.

The Pattern

Always add a comment above your suppression explaining the situation:

// Axios types are incorrect for our custom interceptor setup.
// We've filed issue #1234 with the library maintainers.
// TODO: Remove this once axios@2.0 ships with fixed types.
// @ts-expect-error - axios Response type doesn't account for interceptor transforms
const data = response.customTransformedData;

Or for migration scenarios:

// This legacy module hasn't been migrated to TypeScript yet.
// Scheduled for migration in Q2 2024 sprint (TICKET-456).
// @ts-expect-error - legacyUserService still uses JS with no types
const user = legacyUserService.getUser(id);

What to Include

Your suppression documentation should contain:

  • The specific reason (library bug, migration boundary, dynamic data, etc.)
  • A timeline or trigger for resolution (ticket number, version update, sprint goal)
  • Any workarounds attempted that didn't work
  • Links to issues or discussions when relevant

This turns suppressions from technical debt black holes into tracked, manageable items with clear ownership.

Key Takeaway: Every suppression comment should include a clear explanation of why you're suppressing the error and when or how you expect to resolve it—turning technical debt into documented, trackable work.