ruff: Unify terminology: error vs. check vs. rule

The documentation currently uses all of them switching between them at random. For example in the --help:

  • --select: Comma-separated list of error codes to enable (or ALL, to enable all checks)
  • --exclude List of paths, used to exclude files and/or directories from checks
  • --explain Explain a rule

The README also contains “lint rule” thrice, “lint check” once, “check code prefix” 7 times and “error code prefix” once.

It would be better to use consistent terminology to avoid confusing the user.

Prior art:

Linter Term used
clippy lint(s)
ESLint rule(s)
pyflakes check(s) (but not used often)
pycodestyle check(s) & error code(s)
pydocstyle error(s) & error code(s)

Some thoughts:

  • If rules can be both errors or warnings as suggested in #1256, then we probably want to discontinue any uses of the term “error code”.
  • Ruff is a linter so lint(s) might be the most obvious choice semantically, however users are less likely to be familiar with the noun “lint” than with a more common noun like “rule” or “check”.
  • Some lint(s) perform several checks or enforce several rules. For example TID251 checks both import statements as well as attribute access, T100 checks for several imports, etc. With that in mind “lint(s)” might make the most sense.
  • While it is not strictly necessary that our UI lingo matches the lingo we use within the codebase, I think for the sake of consistency and seamless onboarding of contributors we should aim for consistent terminology throughout the project (CLI, API, documentation). I do consider the consistency of the user-facing terminology to be most important.

About this issue

  • Original URL
  • State: closed
  • Created a year ago
  • Reactions: 2
  • Comments: 17 (17 by maintainers)

Most upvoted comments

When we change this, we should also change the internal convention that “plugin” refers to any function that takes a Checker and adds a rule, where “check” refers to a pure function that returns a Check. It’s super confusing.

Yes, good idea.

My thoughts:

  • For the reasons you describe, I also dislike “error” or “error code”.
  • We probably need two terms: one for the abstract rule (like “lines are too long”), and one for a rule that has been triggered. For example, we could have “rule” and “violation” (in the code, this is basically CheckKind and Check).
  • We also need terms for what are currently called “check code” and “check code prefix”.

I think my preference is “rule” and “violation” (which could be more specifically broken down into errors and warnings, both of which are kinds of violations).