docs: [no-unused-vars] document ignoring `_` prefixed variables

[johnnyreilly]

Before You File a Bug Report Please Confirm You Have Done The Following...

• I have tried restarting my IDE and the issue persists.
• I have updated to the latest version of the packages.
• I have searched for related issues and found none that matched my issue.
• I have read the FAQ and my problem is not listed.

Playground Link

https://typescript-eslint.io/play/#ts=5.3.3&fileType=.tsx&code=MYewdgzgLgBA%2BgSwOZhAJwKYBMCCYsCSAshgIZhQAqIMAvDFGgK4YDcMQA&eslintrc=N4KABBYEQE4PZwC5QFxkTArgUwDTkigAcBDGAZ2xlWgAFEBPI7cgYxgEsjEBaFgGw4A7RAHpSFKlHyRoRfpgDmw8jQDaBCFHpMW7LrwHDkBALozC2AB6JsQgCaq0G2VCMiUMbKzgBbX3b22PbSmnIKykIoOsxsnNx85IIiol4%2B-oHBUGYWWlj8LDSgEAC%2BIGVAA&tsconfig=N4KABGBEDGD2C2AHAlgGwKYCcDyiAuysAdgM6QBcYoEEkJemy0eAcgK6qoDCAFutAGsylBm3TgwAXxCSgA&tokens=false

Repro Code

const _ignoredAndIMeantTo = true;

ESLint Config

module.exports = {
    "root": true,
    "parser": "@typescript-eslint/parser",
    "plugins": [
    "@typescript-eslint"
  ],
    "extends": [
    "eslint:recommended",
    "plugin:@typescript-eslint/recommended"
  ],
    "rules": {
  }
};

tsconfig

{
  "compilerOptions": {
    // ...
  }
}

Expected Result

I'm accustomed to the TypeScript default of accepting that variables prefixed with _ are treated as though they are intentionally ignored.

Actual Result

@typescript-eslint/no-unused-vars does not make use of the same default which I find surprising, and if I may be so bold, disappointing!

It's possible to get the desired behaviour using this rule customisation:

rules: {
        "@typescript-eslint/no-unused-vars": [
            "error",
            { argsIgnorePattern: "^_", varsIgnorePattern: "^_" },
        ],
    },

I'm just curious why typescript-eslint doesn't align with the TypeScript default for similar functionality?

Additional Info

No response

[bradzacher]

We align with the base ESLint rule in all of the options!

The base ESLint rule uses the following config by default:

{
  vars: "all",
  args: "after-used",
  ignoreRestSiblings: false,
  caughtErrors: "all",
}

So that's what we use as well!

This setup allows you to automatically catch all truly useless variables by default and provides no escape hatches to allow unused ones. But note the args: "after-used" which permits the most common need for an escape - function foo(unused1, unused2, used) {...}

This setup is also good because it makes no assumptions about what standard exists in your codebase. Some people like allowing unused vars with an underscore - many don't because it's easy to accidentally use the pattern. Eg some naming conventions use a leading underscore to mean "private".

Its better for the rule to be strict by default and have no false positives rather than loose by default and have false negatives.

There's always the option for people to loosen each usecase with config if they'd like!

---

I definitely understand that it's a convention that TS uses but that doesn't mean it's necessarily a good one! Having a single-character escape hatch by default isn't desirable for a lot of usecases and can mean you accidentally forget to cleanup dead code!

[johnnyreilly]

Thanks for sharing the rationale! I can understand why you might have that default - aligning with ESLint is I guess a straightforward choice.

Speaking personally, I prefer the TypeScript default for a couple of reasons:

• I sometimes (not always) like to have code visible that is being intentionally ignored; it makes me think about that code differently and possibly avoid poor choices I might otherwise make
• It allows for destructuring whereby you intentionally want to throw away some props and hold onto the rest; something like this:

    const {
        formattedDate,
        date: _date,
        ...totals
    } = payload[0].payload as ChartData;

Now I understand your rationale, it seems unlikely you'd change it. For folks like me who have this preference, I may well write a blog post to explain how to set up this rule as (I'd hazard a guess) it might not be only me who likes this!

---

How would you feel about a similar docs contribution to https://typescript-eslint.io/rules/no-unused-vars/ ? That might well help the community who are used to noUnusedLocals and noUnusedParameters.

Particularly given the docs mention this:

For example, the varsIgnorePattern option can customize what names are always allowed to be exempted. TypeScript hardcodes its exemptions to names starting with _.

But don't then talk about how it can be achieved. It might be nice to go on and say "if that is a default that you value, you can enable it with typescript-eslint like so":

rules: {
        "@typescript-eslint/no-unused-vars": [
            "error",
            { argsIgnorePattern: "^_", varsIgnorePattern: "^_" },
        ],
},

[bradzacher]

It allows for destructuring whereby you intentionally want to throw away some props and hold onto the rest; something like this:

You might be interested in the ignoreRestSiblings option (which is off by default). playground.

[johnnyreilly]

Oh that looks nice! Yeah I'd use that.

[bradzacher]

Yeah personally I've always been of two minds about the underscore pattern.
On the one hand it is nice to have a short-hand to ignore things.
On the other hand it is terrible having a short-hand to ignore things - it's a single character that's easy to miss in code review - so it's easy to sneak into a commit.

For example I recently reviewed a PR where someone innocently did something like

import { promisify } from 'node:util';
import { exec as _exec } from 'node:child_process';

const exec = promisify(_exec);

And they didn't realise that doing this would define a variable that would never get flagged if it's unused! Really bad!

So yeah - it's a mixed bag, IMO - there needs to be a way to say "if this variable is used it mustn't start with _".

[bradzacher]

How would you feel about a similar docs contribution to typescript-eslint.io/rules/no-unused-vars ? That might well help the community who are used to noUnusedLocals and noUnusedParameters.

Sure! Always happy to expand on the docs.