programming.protips.wiki
githubtwitter

Give a reason when using suppression statements

#types #linter

Add a description to suppression statements used to silence warnings from linters and type checkers to tell us why it's being silenced.

Bad Examples

// $FlowFixMe
/* istanbul ignore if */
// eslint-disable-next-line no-alert

Prefer

// $FlowFixMe: The typings for this method are out of date. TODO: Use new version when released (MYJIRA-1234)
/* istanbul ignore if: sanity check  */
// TODO(MYJIRA-1234): Create and use a design system modal component. For now, we're using alert :(
// eslint-disable-next-line no-alert

Tips:

  • If your project uses a bug tacker or GitHub issues, create or link to a ticket in the description
  • Include a sample stack trace so readers can understand the failure case, and to make it searchable

Why?

Without a description, it may not be obvious to the reader of the code why the line is being suppressed, and if or when in the future it can be removed.

Suppression statements are powerful and can mask buggy code that would otherwise be caught - it's usually good to communicate why it's being used, so readers of the code can understand the tradeoff and the need for employing it.