[clang-tidy] Add a check for enforcing minimum length for variable names

[0x8000-0000]

Summary

Add a check for enforcing minimum length for variable names. A default minimum length of three characters is applied to regular variables (including function parameters). Loop counters and exception variables have a minimum of two characters. Additionally, the 'i', 'j' and 'k' are accepted as legacy values.

All three sizes, as well as the list of accepted legacy loop counter names are configurable.

[0x8000-0000]

Rebased on main branch. Added missing documentation and release notes.

[0x8000-0000]

Clean-up messy rebase for the checks/list.rst .

[Eugene.Zelenko]

clang-tools-extra/clang-tidy/readability/VariableLengthCheck.cpp

35

Please don't use auto unless type is explicitly spelled in same statement or iterator.

94

Please don't use auto unless type is explicitly spelled in same statement or iterator.

clang-tools-extra/docs/clang-tidy/checks/readability-variable-length.rst

7

Please synchronize with statement in Release Notes.

10

See other checks documentation as example of options descriptions.

16

Please highlight default value with single back-quote. Same below.

[njames93]

Please can you upload diffs with full context or using arcanist.

It may be worth adding a case where if the Minimum<Type>NameLength is set to 0, it won't check that type, or even bother registering its matchers.

It may be worth adding unless(isImplicit()) to each varDecl() matcher, save any nasties from compiler generated decls.

clang-tools-extra/clang-tidy/readability/VariableLengthCheck.cpp

24

If you make this regex this could be changed to "^[ijk]$".

31

For better or worse, we typically use parentheses instead of braced initialization for the member init list.

44–51

You shouldn't be storing the default value, you should be storing the value read from config.

55–56

This code will match i, j and k in this example

for (int i = 4, j = 5;;)
  int k = 5;

It may be better to use this:

// To match both i and j
forStmt(hasLoopInit(declStmt(forEach(varDecl().bind("loopVar")))))
// To only match i
forStmt(hasLoopInit(declStmt(containsDeclaration(0, varDecl().bind("loopVar")))))

59–63

This will miss the match for k in the same example:

for (int i = 4, j = 5;;)
  int k = 5;

Gotta scratch my head for this one though. Though like the case before its rather unlikely to show up in code so not the end of the world.

Also varDecl will match parameters, is this intended can you add tests and explain in documentation.
If its unintended putting unless(parmVarDecl()) in the matcher disable that.

73–75

This message can(should) be reused for all warnings with select.
Obviously you'd put that in a char arrray and the reference it for the next 2 diags.

clang-tools-extra/clang-tidy/readability/VariableLengthCheck.h

21

Full-stop/period at the end of comments.

37

I feel like regex is better suited for this purpose and just ignore any loop variables that match the regex.
Doing this will require storing a string as well as the regex for the purpose of storeOptions.

[0x8000-0000]

@Eugene.Zelenko and @njames93

Thank you both for the kind and thoughtful feedback. I am incorporating all recommended changes.

First step are all the smaller scope comments, with regex support in a follow-up commit.

I will also generate the diffs in the future using the -U99999 option as suggested.

clang-tools-extra/clang-tidy/readability/VariableLengthCheck.cpp

59–63

Matching of function parameter names is intentional. I will make sure it is emphasized in the documentation.

[0x8000-0000]

Addressed most of the review comments with the exception of switching to regex for ignoring loop counters; this change is in the follow-up review.

[Eugene.Zelenko]

clang-tools-extra/docs/clang-tidy/checks/readability-variable-length.rst

10

You still need to add Options section and mark-up for options. See other checks documentation as example.

[0x8000-0000]

clang-tools-extra/docs/clang-tidy/checks/readability-variable-length.rst

10

Oh, sorry, now I see what you mean. I have sampled randomly a handful of documentation snippets, and didn't find anything. But after your comment, I looked at readability-identifier-naming.rst which had "options" in all their glory.

[0x8000-0000]

Use regular expression for filtering out loop counter variables to ignore.

Fully document the options.

[Eugene.Zelenko]

clang-tools-extra/docs/clang-tidy/checks/readability-variable-length.rst

22

It'll be good idea to use 2 symbols indention, like in code. Same in other places.

[0x8000-0000]

Add an option "IgnoredVariableNames" that allows filtering out acceptable variable names (similar to the loop counters); also implemented via regex.

Added tests for the IgnoredVariableNames option.

[0x8000-0000]

Ping?

[aaron.ballman]

clang-tools-extra/clang-tidy/readability/ReadabilityTidyModule.cpp

136

Is there a reason this should be restricted to variables? For example, wouldn't the same functionality be useful for type names, or dare I say it, even macro names? I'm wondering if this should be readability-identifier-length to be more generic.

clang-tools-extra/clang-tidy/readability/VariableLengthCheck.cpp

21

Should it be possible to enforce parameters differently than local variables? (It seems a bit odd that we'd allow you to specify exception variable length separate from loops but not function parameters separate from locals.)

25

Ignored exception names? There's a fair amount of catch (const exception &e) code in the world: https://codesearch.isocpp.org/cgi-bin/cgi_ppsearch?q=catch%28const+exception+%26e%29&search=Search)

27

It looks like there will be whitespace issues with this. If the variable is a loop or exception, it'll have an extra space (loop variable name) and if it's not, it will start with a leading space ( variable name).

[0x8000-0000]

Added regex for exception names and rebased onto current 'main' branch.

clang-tools-extra/clang-tidy/readability/ReadabilityTidyModule.cpp

136

I consider those to be in separate namespaces. I suppose we could have a single checker with multiple rules, but on the other hand I don't want to combine too many things into one, just because they share the "compare length" dimension.

clang-tools-extra/clang-tidy/readability/VariableLengthCheck.cpp

21

Exceptions and Loops historically are "throw-away" / "don't care" / "one-off" variables. Parameter names are names, and they are the interface between the outside of the routine and the processing inside; other than historical, I don't see good arguments (sic) to allow single-letter parameter names.

Note that this check will be quite noisy on a legacy code base, and people will find little reason to invest the work to remove the warnings. But if somebody starts something new and want to enforce some quality attributes, it is the right tool at the right time. There will be new projects starting in 2021 and 2022 that could benefit from this, I hope.

27

This was recommended by a previous reviewer. Any alternative suggestion here?

[0x8000-0000]

Added separate check for parameter names.

[0x8000-0000]

Updated documentation for all options.

[aaron.ballman]

clang-tools-extra/clang-tidy/readability/ReadabilityTidyModule.cpp

136

I see where you're coming from, but I come down on the other side. Running a check is expensive (especially on Windows where process creation can be really slow), so having multiple checks that traverse the AST gives worse performance than having a single check that only traverses the AST once. I'd rather see related functionality grouped together and use options to control behavior when it's a natural fit to do so.

I should note that I don't mean *you* have to implement this other functionality (as part of this patch or otherwise). Just that I think we should leave the check name ambiguous enough that we could grow it to do that work in the future.

WDYT?

clang-tools-extra/clang-tidy/readability/VariableLengthCheck.cpp

21

Exceptions and Loops historically are "throw-away" / "don't care" / "one-off" variables. Parameter names are names, and they are the interface between the outside of the routine and the processing inside; other than historical, I don't see good arguments (sic) to allow single-letter parameter names.

I largely agree with you, but there are definitely cases where single-letter parameter names are extremely common. For example, coordinates are often x, y, and z, colors are often r, g, and b (among many others), and physics applications often do things like f = m * a with their variables. Also, there are cases where the parameter names are often not super meaningful, like with functions min and max so the parameter names may be quite short.

27

I *think* the diagnostic will work if you write it like this:
"%select{variable |exception variable |loop variable |parameter }0name %1 is too short, expected at least %2 characters"

99

115

129

144

clang-tools-extra/test/clang-tidy/checkers/readability-variable-length.cpp

45

What in the configuration causes n to be ignored?

[0x8000-0000]

clang-tools-extra/clang-tidy/readability/ReadabilityTidyModule.cpp

136

Right - that's a good point. But I'm wondering the other way; maybe the bigger check will subsume this one, and this one will become just an alias for the bigger check?

So I'm -0.1 on using the "bigger name" for the limited functionality, but if one more vote comes in saying to go readability-identifier-length I'll rename this (and add explicitly the scope limits in the documentation.)

clang-tools-extra/clang-tidy/readability/VariableLengthCheck.cpp

21

Indeed - I have changed the code to meet this capability; now parameters are controlled independently of the regular variables.

clang-tools-extra/test/clang-tidy/checkers/readability-variable-length.cpp

45

It is ignored by the default configuration. Search for "DefaultIgnoredParameterNames" above.

[aaron.ballman]

clang-tools-extra/clang-tidy/readability/ReadabilityTidyModule.cpp

136

Right - that's a good point. But I'm wondering the other way; maybe the bigger check will subsume this one, and this one will become just an alias for the bigger check?

The downside to that approach is that the alias is a bit confusing until its deprecation period ends and we remove it. However, that's not a huge downside., so I don't insist on the name change if you're resistant to it.

clang-tools-extra/test/clang-tidy/checkers/readability-variable-length.cpp

45

Ah, the comment tripped me up -- can you say ignored via default configuration like below to make it more clear?

[0x8000-0000]

clang-tools-extra/clang-tidy/readability/ReadabilityTidyModule.cpp

136

I can do the rename, but my intuition (informed somewhat by a few years in the industry) is that outside of T as template argument and X for X-Macros, there aren't many single or even two letter class names or structures out there outside of intentionally obfuscated code - thus I don't think there will be a need to have readability-identifier-length produced.

To avoid potential churn and the hassle with deprecation I'll make the change though.

clang-tools-extra/test/clang-tidy/checkers/readability-variable-length.cpp

45

Sorry about that; fixed in next patch.

[0x8000-0000]

Rebased on main and renamed from readability-variable-length to readability-identifier-length.

[0x8000-0000]

Clean diff against origin/main

[aaron.ballman]

LGTM aside from some style nits (removing some top-level const we don't typically use, unnecessary paren expressions, and a typo fix), thank you for the check!

clang-tools-extra/clang-tidy/readability/IdentifierLengthCheck.cpp

99 ↗

(On Diff #365651)

101 ↗

(On Diff #365651)

115–116 ↗

(On Diff #365651)

129 ↗

(On Diff #365651)

144 ↗

(On Diff #365651)

clang-tools-extra/docs/clang-tidy/checks/readability-identifier-length.rst

81 ↗

(On Diff #365651)

[0x8000-0000]

Removed extra 'const' and parentheses that are not congruent with the accepted code style.

[0x8000-0000]

@aaron.ballman - thank you for the review; please submit on my behalf.

[0x8000-0000]

Reformatted the test file.

[0x8000-0000]

One more format nit.

[aaron.ballman]

In D97753#2940414, @0x8000-0000 wrote:

@aaron.ballman - thank you for the review; please submit on my behalf.

Happy to do so, which name and email address would you like me to use for patch attribution?

[0x8000-0000]

The diff was generated with format-patch, so can be applied with "git am".

The envelope:

commit d98d336b452876cfbc32ad1b76319912c45b646b (HEAD -> readability-variable-name-length-main)
Author: Florin Iucha <[e-mail]>
Date: Mon Mar 1 00:57:01 2021 -0500

Add a checker for variable name length

It requires regular variables and parameters names to be at least
three characters long, and loop variables and exception names to be at
least two characters long. Exceptions to these minimums can be added
via regular expressions.

[aaron.ballman]

In D97753#2941277, @0x8000-0000 wrote:

The diff was generated with format-patch, so can be applied with "git am".

The envelope:

commit d98d336b452876cfbc32ad1b76319912c45b646b (HEAD -> readability-variable-name-length-main)
Author: Florin Iucha <[e-mail]>
Date: Mon Mar 1 00:57:01 2021 -0500

Thanks! When I go to download the diff from Phab, it drops the envelope so all I have is the diff. :-)

I've commit on your behalf in d2c5cbc3a856c2f8bbda05540fa761bb94ba32f6

clang-tools-extra/clang-tidy/readability/CMakeLists.txt

   UniqueptrDeleteReleaseCheck.cpp
   UppercaseLiteralSuffixCheck.cpp
   UseAnyOfAllOfCheck.cpp
+  VariableLengthCheck.cpp
 
   LINK_LIBS
   clangTidy

clang-tools-extra/clang-tidy/readability/ReadabilityTidyModule.cpp

 #include "UniqueptrDeleteReleaseCheck.h"
 #include "UppercaseLiteralSuffixCheck.h"
 #include "UseAnyOfAllOfCheck.h"
+#include "VariableLengthCheck.h"
 
 namespace clang {
 namespace tidy {

         "readability-uppercase-literal-suffix");
     CheckFactories.registerCheck<UseAnyOfAllOfCheck>(
         "readability-use-anyofallof");
+    CheckFactories.registerCheck<VariableLengthCheck>(
+        "readability-variable-length");
   }
 };
 

clang-tools-extra/clang-tidy/readability/VariableLengthCheck.h

+//===--- VariableLengthCheck.h - clang-tidy ---------------------*- C++ -*-===//
+//
+// Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
+// See https://llvm.org/LICENSE.txt for license information.
+// SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
+//
+//===----------------------------------------------------------------------===//
+
+#ifndef LLVM_CLANG_TOOLS_EXTRA_CLANG_TIDY_READABILITY_VARIABLELENGTHCHECK_H
+#define LLVM_CLANG_TOOLS_EXTRA_CLANG_TIDY_READABILITY_VARIABLELENGTHCHECK_H
+
+#include "../ClangTidyCheck.h"
+#include "llvm/Support/Regex.h"
+
+namespace clang {
+namespace tidy {
+namespace readability {
+
+/// Warns about variable names whose length is too short.
+///
+/// For the user-facing documentation see:
+/// http://clang.llvm.org/extra/clang-tidy/checks/readability-variable-length.html
+class VariableLengthCheck : public ClangTidyCheck {
+public:
+  VariableLengthCheck(StringRef Name, ClangTidyContext *Context);
+  void storeOptions(ClangTidyOptions::OptionMap &Opts) override;
+  void registerMatchers(ast_matchers::MatchFinder *Finder) override;
+  void check(const ast_matchers::MatchFinder::MatchResult &Result) override;
+
+private:
+  const unsigned MinimumVariableNameLength;
+  const unsigned MinimumLoopCounterNameLength;
+  const unsigned MinimumExceptionNameLength;
+  const unsigned MinimumParameterNameLength;
+
+  std::string IgnoredVariableNamesInput;
+  llvm::Regex IgnoredVariableNames;
+
+  std::string IgnoredLoopCounterNamesInput;
+  llvm::Regex IgnoredLoopCounterNames;
+
+  std::string IgnoredExceptionVariableNamesInput;
+  llvm::Regex IgnoredExceptionVariableNames;
+
+  std::string IgnoredParameterNamesInput;
+  llvm::Regex IgnoredParameterNames;
+};
+
+} // namespace readability
+} // namespace tidy
+} // namespace clang
+
+#endif // LLVM_CLANG_TOOLS_EXTRA_CLANG_TIDY_READABILITY_VARIABLELENGTHCHECK_H

clang-tools-extra/clang-tidy/readability/VariableLengthCheck.cpp

+//===--- VariableLengthCheck.cpp - clang-tidy -----------------------------===//
+//
+// Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
+// See https://llvm.org/LICENSE.txt for license information.
+// SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
+//
+//===----------------------------------------------------------------------===//
+
+#include "VariableLengthCheck.h"
+#include "../utils/OptionsUtils.h"
+#include "clang/AST/ASTContext.h"
+#include "clang/ASTMatchers/ASTMatchFinder.h"
+
+using namespace clang::ast_matchers;
+
+namespace clang {
+namespace tidy {
+namespace readability {
+
+const unsigned DefaultMinimumVariableNameLength = 3;
+const unsigned DefaultMinimumLoopCounterNameLength = 2;
+const unsigned DefaultMinimumExceptionNameLength = 2;
+const unsigned DefaultMinimumParameterNameLength = 3;
+const char DefaultIgnoredLoopCounterNames[] = "^[ijk_]$";
+const char DefaultIgnoredVariableNames[] = "";
+const char DefaultIgnoredExceptionVariableNames[] = "^[e]$";
+const char DefaultIgnoredParameterNames[] = "^[n]$";
+
+const char ErrorMessage[] =
+    "%select{variable|exception variable|loop variable|"
+    "parameter}0 name %1 is too short, expected at least %2 characters";
+
+VariableLengthCheck::VariableLengthCheck(StringRef Name,
+                                         ClangTidyContext *Context)
+    : ClangTidyCheck(Name, Context),
+      MinimumVariableNameLength(Options.get("MinimumVariableNameLength",
+                                            DefaultMinimumVariableNameLength)),
+      MinimumLoopCounterNameLength(Options.get(
+          "MinimumLoopCounterNameLength", DefaultMinimumLoopCounterNameLength)),
+      MinimumExceptionNameLength(Options.get(
+          "MinimumExceptionNameLength", DefaultMinimumExceptionNameLength)),
+      MinimumParameterNameLength(Options.get(
+          "MinimumParameterNameLength", DefaultMinimumParameterNameLength)),
+      IgnoredVariableNamesInput(
+          Options.get("IgnoredVariableNames", DefaultIgnoredVariableNames)),
+      IgnoredVariableNames(IgnoredVariableNamesInput),
+      IgnoredLoopCounterNamesInput(Options.get("IgnoredLoopCounterNames",
+                                               DefaultIgnoredLoopCounterNames)),
+      IgnoredLoopCounterNames(IgnoredLoopCounterNamesInput),
+      IgnoredExceptionVariableNamesInput(
+          Options.get("IgnoredExceptionVariableNames",
+                      DefaultIgnoredExceptionVariableNames)),
+      IgnoredExceptionVariableNames(IgnoredExceptionVariableNamesInput),
+      IgnoredParameterNamesInput(
+          Options.get("IgnoredParameterNames", DefaultIgnoredParameterNames)),
+      IgnoredParameterNames(IgnoredParameterNamesInput) {}
+
+void VariableLengthCheck::storeOptions(ClangTidyOptions::OptionMap &Opts) {
+  Options.store(Opts, "MinimumVariableNameLength", MinimumVariableNameLength);
+  Options.store(Opts, "MinimumLoopCounterNameLength",
+                MinimumLoopCounterNameLength);
+  Options.store(Opts, "MinimumExceptionNameLength", MinimumExceptionNameLength);
+  Options.store(Opts, "MinimumParameterNameLength", MinimumParameterNameLength);
+  Options.store(Opts, "IgnoredLoopCounterNames", IgnoredLoopCounterNamesInput);
+  Options.store(Opts, "IgnoredVariableNames", IgnoredVariableNamesInput);
+  Options.store(Opts, "IgnoredExceptionVariableNames",
+                IgnoredExceptionVariableNamesInput);
+  Options.store(Opts, "IgnoredParameterNames", IgnoredParameterNamesInput);
+}
+
+void VariableLengthCheck::registerMatchers(MatchFinder *Finder) {
+  if (MinimumLoopCounterNameLength > 1)
+    Finder->addMatcher(
+        forStmt(hasLoopInit(declStmt(forEach(varDecl().bind("loopVar"))))),
+        this);
+
+  if (MinimumExceptionNameLength > 1)
+    Finder->addMatcher(varDecl(hasParent(cxxCatchStmt())).bind("exceptionVar"),
+                       this);
+
+  if (MinimumParameterNameLength > 1)
+    Finder->addMatcher(parmVarDecl().bind("paramVar"), this);
+
+  if (MinimumVariableNameLength > 1)
+    Finder->addMatcher(
+        varDecl(unless(anyOf(hasParent(declStmt(hasParent(forStmt()))),
+                             hasParent(cxxCatchStmt()), parmVarDecl())))
+            .bind("standaloneVar"),
+        this);
+}
+
+void VariableLengthCheck::check(const MatchFinder::MatchResult &Result) {
+  const auto *StandaloneVar = Result.Nodes.getNodeAs<VarDecl>("standaloneVar");
+  if (StandaloneVar) {
+    if (!StandaloneVar->getIdentifier())
+      return;
+
+    const StringRef VarName = StandaloneVar->getName();
+
+    if ((VarName.size() >= MinimumVariableNameLength) ||
+        IgnoredVariableNames.match(VarName))
+      return;
+
+    diag(StandaloneVar->getLocation(), ErrorMessage)
+        << 0 << StandaloneVar << MinimumVariableNameLength;
+  }
+
+  const auto *ExceptionVarName =
+      Result.Nodes.getNodeAs<VarDecl>("exceptionVar");
+  if (ExceptionVarName) {
+    if (!ExceptionVarName->getIdentifier())
+      return;
+
+    const StringRef VarName = ExceptionVarName->getName();
+    if ((VarName.size() >= MinimumExceptionNameLength) ||
+        IgnoredExceptionVariableNames.match(VarName))
+      return;
+
+    diag(ExceptionVarName->getLocation(), ErrorMessage)
+        << 1 << ExceptionVarName << MinimumExceptionNameLength;
+  }
+
+  const auto *LoopVar = Result.Nodes.getNodeAs<VarDecl>("loopVar");
+  if (LoopVar) {
+    if (!LoopVar->getIdentifier())
+      return;
+
+    const StringRef VarName = LoopVar->getName();
+
+    if (VarName.size() >= MinimumLoopCounterNameLength ||
+        IgnoredLoopCounterNames.match(VarName))
+      return;
+
+    diag(LoopVar->getLocation(), ErrorMessage)
+        << 2 << LoopVar << MinimumLoopCounterNameLength;
+  }
+
+  const auto *ParamVar = Result.Nodes.getNodeAs<VarDecl>("paramVar");
+  if (ParamVar) {
+    if (!ParamVar->getIdentifier())
+      return;
+
+    const StringRef VarName = ParamVar->getName();
+
+    if (VarName.size() >= MinimumParameterNameLength ||
+        IgnoredParameterNames.match(VarName))
+      return;
+
+    diag(ParamVar->getLocation(), ErrorMessage)
+        << 3 << ParamVar << MinimumParameterNameLength;
+  }
+}
+
+} // namespace readability
+} // namespace tidy
+} // namespace clang

clang-tools-extra/docs/ReleaseNotes.rst

 New checks
 ^^^^^^^^^^
 
+- New :doc:`readability-variable-length
+  <clang-tidy/checks/readability-variable-length>` check.
+
+  Finds variables and function arguments whose names are too short.
+
 New check aliases
 ^^^^^^^^^^^^^^^^^
 

clang-tools-extra/docs/clang-tidy/checks/list.rst

    `readability-uniqueptr-delete-release <readability-uniqueptr-delete-release.html>`_, "Yes"
    `readability-uppercase-literal-suffix <readability-uppercase-literal-suffix.html>`_, "Yes"
    `readability-use-anyofallof <readability-use-anyofallof.html>`_,
+   `readability-variable-length <readability-variable-length.html>`_,
    `zircon-temporary-objects <zircon-temporary-objects.html>`_,
 
 

clang-tools-extra/docs/clang-tidy/checks/readability-variable-length.rst

+.. title:: clang-tidy - readability-variable-length
+
+readability-variable-length
+===========================
+
+This check finds variables and function parameters whose length are too short.
+The desired name length is configurable.
+
+Special cases are supported for loop counters and for exception variable names.
+
+Options
+-------
+
+The following options are described below:
+
+ - :option:`MinimumLoopCounterNameLength`, :option:`IgnoredLoopCounterNames`
+ - :option:`MinimumVariableNameLength`, :option:`IgnoredVariableNames`
+ - :option:`MinimumExceptionNameLength`
+
+.. option:: MinimumLoopCounterNameLength
+
+    Loop counter variables are expected to have a length of at least
+    `MinimumLoopCounterNameLength` characters (default is `2`).
+
+    .. code-block:: c++
+
+      // This warns that 'q' is too short.
+      for (int q = 0; q < size; ++ q) {
+         // ...
+      }
+
+.. option:: IgnoredLoopCounterNames
+
+    Specifies a regular expression for counter names that are to be ignored.
+    The default value is `^[ijk_]$`; the first three symbols for historical
+    reasons and the last one since it is frequently used as a "dont't care"
+    value, specifically in tools such as Google Benchmark.
+
+    .. code-block:: c++
+
+      // This does not warn by default, for historical reasons.
+      for (int i = 0; i < size; ++ i) {
+          // ...
+      }
+
+.. option:: MinimumExceptionNameLength
+
+    Exception clause variables are expected to have a length of at least
+    `MinimumExceptionNameLength` (default is `2`).
+
+    .. code-block:: c++
+
+      try {
+          // ...
+      }
+      // This warns that 'e' is too short.
+      catch (const std::exception& e) {
+          // ...
+      }
+
+.. option:: MinimumVariableNameLength
+
+    All other variables are expected to have at least a length of
+    `MinimumVariableNameLength` (default is `3`).
+
+    .. code-block:: c++
+
+      int i = 42;    // warns that 'i' is too short
+
+    This check does not have any fix suggestions in the general case since
+    variable names have semantic value.
+
+.. option:: IgnoredVariableNames
+
+    Specifies a regular expression for variable names and parameters that are
+    to be ignored. The default value is empty, thus no names are ignored.

clang-tools-extra/test/clang-tidy/checkers/readability-variable-length.cpp

+// RUN: %check_clang_tidy %s readability-variable-length %t \
+// RUN: -config='{CheckOptions: \
+// RUN:  [{key: readability-variable-length.IgnoredVariableNames, value: "^[xy]$"}]}' \
+// RUN: --
+
+struct myexcept
+{
+   int val;
+};
+
+struct simpleexcept
+{
+   int other;
+};
+
+void doIt();
+
+void tooShortVariableNames(int z)
+// CHECK-MESSAGES: :[[@LINE-1]]:32: warning: parameter name 'z' is too short, expected at least 3 characters [readability-variable-length]
+{
+   int i = 5;
+// CHECK-MESSAGES: :[[@LINE-1]]:8: warning: variable name 'i' is too short, expected at least 3 characters [readability-variable-length]
+
+   int jj = z;
+// CHECK-MESSAGES: :[[@LINE-1]]:8: warning: variable name 'jj' is too short, expected at least 3 characters [readability-variable-length]
+
+   for (int m = 0; m < 5; ++ m)
+// CHECK-MESSAGES: :[[@LINE-1]]:13: warning: loop variable name 'm' is too short, expected at least 2 characters [readability-variable-length]
+   {
+      doIt();
+   }
+
+   try
+   {
+      doIt();
+   }
+   catch (const myexcept& x)
+// CHECK-MESSAGES: :[[@LINE-1]]:27: warning: exception variable name 'x' is too short, expected at least 2 characters [readability-variable-length]
+   {
+      doIt();
+   }
+}
+
+void longEnoughVariableNames(int n) // argument 'n' ignored by configuration
+{
+   int var = 5;
+
+   for (int i = 0; i < 42; ++ i) // 'i' is default allowed, for historical reasons
+   {
+      doIt();
+   }
+
+   for (int kk = 0; kk < 42; ++ kk)
+   {
+      doIt();
+   }
+
+   try
+   {
+      doIt();
+   }
+   catch (const simpleexcept& e) // ignored via default configuration
+   {
+      doIt();
+   }
+   catch (const myexcept& ex)
+   {
+      doIt();
+   }
+
+   int x = 5;  // ignored by configuration
+}