h/t @johnnyreilly.com for suggesting an article on this very important question!

Comment directives are a "necessary evil" for static analysis tools such as TypeScript.

If you'd like to learn more, see the blog post at the top of this thread: www.learningtypescript.com/articles/com...

Got your own TypeScript Qs? Ask and I'll be happy to answer. 💙

Thanks for reading!

11/11

Finally, answering an FAQ: different tools use different comment directives. TypeScript doesn't recognize Biome's, ESLint's, Prettier, etc. ESLint doesn't recognize // ts-expect-error, ts-ignore, etc.

typescript-eslint.io/troubleshoot...

10/🧵

You can also lint for comment directives!

@typescript-eslint.io's `@typescript-eslint/ban-ts-comment` reports if you:
* use a ts-ignore or ts-nocheck directive
* forget to attach an explanation >3 characters on a ts-expect-error directive

Use linting to enforce and teach best practices. 🧠

9/🧵

Let's talk about some best practices around comment directives. There's more than just "prefer ts-expect-error".

First, put explanations with your comment directives. These will help future developers understand why you had to use them - and show that they're not to be used willy-nilly.

8/🧵

On a brighter note, the `// @ts-check` comment directive *enables* type checking for a file. This can be handy if you're running TypeScript on JavaScript source files and haven't been able to enable checkJs: true yet.

7/🧵

The `// @ts-nocheck` comment directive completely disables type checking for an entire file. Even more so than the per-line directives, you should almost never use this. ⛔️

But, it can be handy if you don't have the time to convert a large existing file to TypeScript.

6/🧵

`// @ts-ignore` is the same as `// @ts-expect-error`, but is allowed to exist and not do anything. This can be useful if you're testing across multiple TypeScript versions or running into other tooling edge case.

5/🧵

If you absolutely must disable type checking for a line, almost always prefer `// @ts-expect-error`. It:

* Disables type checking on a line
* Reports a type error if the comment isn't suppressing any

Being told when a comment directive can be removed helps with long-term code cleanliness.

4/🧵

Most of the time, you don't want "disable type checking" comment directives. Type checking is good! Avoiding type errors is good!

Sometimes the type checker can be wrong. Types can be incorrect, or there can be a bug or missing feature.

If an `any` isn't enough, a comment directive might be.

3/🧵

A comment directive is a comment that directs (changes) how a tool operates within a file. TypeScript includes several that can change type checking behavior for a file or on a specific line.

The most common are `@ts-expect-error` & `@ts-ignore`, which disable type checking for a line.

2/🧵