programming.protips.wiki
githubtwitter
/give-reason-for-suppression
#typechecker #linter #supression-statements

Give a reason when using suppression statements

Add a description to suppression statements telling us why it's being silenced. A comment like "x is wrong" is almost never sufficient (if it really is wrong, please file a bug report and link to it in the comment).

Bad:

// $FlowFixMe
// $FlowFixMe: typedefs for this function is wrong
/* istanbul ignore if */
// eslint-disable-next-line no-alert

Good:

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

Tips:

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.