Use semantic variable names
Variable names should be descriptive and capture the semantics of the value they represent. This makes it easier to read and understand code. It also makes it clearer when variables are being misused.
Caveats
An exception to this rule is that it is acceptable to use simple variable names like i
in for
loops.
An exception to this rule is that math-heavy code may use simple variable names within the scope of a mathematically dense function.
Common acronyms like api
, ast
, and llm
are fine even though they aren’t as descriptive.
res
, result
, and data
are common exceptions that are okay to ignore.
Variables names which mirror the corresponding type name are okay to ignore.
Keys in objects and JS/TS strings are not variable names, so they should be ignored.
If a value isn’t a variable name, then it should be ignored.
This rule should be ignored in test files.
The names of file imports from third-party APIs and modules should be ignored because we have no control over them.
If you are unsure whether or not a variable name is descriptive enough, err on the side of caution by setting confidence
to low
.
Examples
Incorrect Examples
// Bad because "a" is not a descriptive variable name
const a = 5
// Bad because "b" is not a descriptive variable name
const b = false
// Bad because "obj" is not a descriptive variable name
const obj = { id: 5, name: 'Bob' }
Correct Examples
// Good because "numTokens" is descriptive
const numTokens = 5
// Good because "isFinished" is descriptive
const isFinished = true
// Good because "ast" is an acronym
const ast = parseAST()
// Good because "fileTypeToParserMap" is very descriptive
const fileTypeToParserMap: Record<string, string> = {}
// "i" is okay here because it is a simple for loop
for (let i = 0; i < 10; i++) {}
// "x", "y", and "r" are all okay here because they represent real, mathematical
// concepts, and concise variable names are often preferred in math-heavy code.
function normalDist(mu = 0, sigma = 1) {
let x: number, y: number, r: number
do {
x = Math.random() * 2 - 1
y = Math.random() * 2 - 1
r = x * x + y * y
} while (!r || r > 1)
return mu + sigma * y * Math.sqrt((-2 * Math.log(r)) / r)
}
// These are fine because the simple variable names match the corresponding type names.
const rule: Rule = {}
const data: Data = {}
// This is fine because `z` is an external dependency that we have no control over.
import { z } from 'zod'
Metadata
Key | Value |
---|---|
name | semantic-variable-names |
level | error |
scope | file |
fixable | false |
cacheable | true |
tags | [ best practices ] |
exclude | [ **/*\.test\.{js,ts,jsx,tsx,cjs,mjs} ] |
gritqlNumLinesContext | 2 |
gritql | true |