[clang-tidy][doc] Document readability-indentifier-naming resolution order and examples

[KazNX]

Summary

Added extensive documentation to identify the order in which readability-identifier-naming attempts to resolve its classifications. This is followed by an exhaustive code example covering all identifiers commented with their appropriate classifications. This seeks to provide improved information for those seeking to define a particular naming standard.

[Eugene.Zelenko]

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

2747

Please make length same as title.

2762

Extra back-tick.

2854

Clang-tidy.

2857

Ditto.

2862

Ditto.

[LegalizeAdulthood]

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

2742

Phabricator says there is no context available. Did you generate this diff with git diff -U999999 main?

2750

fall, not falling

2750

Below, not Bellow

2756

Does it have to be in the .clang-tidy file, or is it just a matter of setting options?

2772

Why is Struct listed twice?

2786

I would have expected ConstExprVariable instead?

2857

identifies, not identifiers

2873

parameters not paramaters

2873

Clang-tidy, not clang tidy

2880

Should we be linking to ephemeral gists that can disappear?

3054

This covers "const pointer", but what about "pointer to const"?
e.g. std::string const *str_ptr how is this handled?

3120

Same, pointer to const?

3127–3129

Is this really a bug report disguised as a doc comment?

[KazNX]

Updated to address feedback.

• Typo corrections.
• Additional declarations.
• Changed source reference URL.

[whisperity]

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

2750–2752

So is this resolution order the same for every Decl?

2880

Are the contents of the file linked and the one in the documentation here the exact same? In that case I think if the author gives rights for LLVM to use their work, we can get rid of the link, as it serves no additional value.

[KazNX]

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

2742

No sorry. Will fix on next submission.

2750–2752

Not as I found it. IdentifierNamingCheck::findStyleKind() is laid out mostly in an ordered fashion, but some checks necessarily repeat either in different context or because of shared semantics. The best example I have is the struct vs class relationship. A struct will first be idenified as SK_Struct, but if there's no naming for that, then it will try SK_Class. Meanwhile, a class does the same thing in the opposite order; first SK_Class then SK_Struct.

2756

I've changed the wording.

2772

This is a reflection of what actually happes. For a struct, it tries to resovle first as a struct, then as a class. Meanwhile, for a class it tries class first then struct. Note the accompanying keywords.

This is also addressed in the paragraph above the list.

Some classifications appear multiple times as they can be checked in different

2786

That's not the case I'm seeing in code or in the documentation. See https://clang.llvm.org/extra/clang-tidy/checks/readability-identifier-naming.html#cmdoption-arg-constexprvariablecase

2857

Intentionaly. I'm using the noun, not the verb.

2880

I'm changing this link to a full repo.

2880

Yeah, I'm no expert on all this, but I am the author of both. If I had submitted a patch first then I've wouldn't have included the link.

To answer directly, the contents has only minor differences.

3054

I can add that. Empirically that turned out a ConstantParameter.

3054

I was wrong. There's no const association.

3120

I'm adding a few more variants including static.

3127–3129

Yes it is. Sorry, was captured from my original document. I agree it doesn't belong here.

3127–3129

I've added a new bug report for this: https://github.com/llvm/llvm-project/issues/55705

[LegalizeAdulthood]

Clang-Tidy tests and docs have moved to module subdirectories.

Please rebase this onto main:HEAD and:

• fold your changes into the appropriate subdirs, stripping the module prefix from new files.
• make the target check-clang-extra to validate your tests
• make the target docs-clang-tools-html to validate any docs changes

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

     double   dValueDouble = 0.0;
     ULONG    ulValueUlong = 0;
     DWORD    dwValueDword = 0;
+
+Resolution order
+-------
+
+The full set of identifier classifications listed above includes some overlap,
+where an individual identifier can falling into several classifications. Bellow
+is a list of the classifications supported by ``readability-identifier-naming``
+presented in the order in which the classifications are resolved. Some
+classifications appear multiple times as they can be checked in different
+contexts. The check returns as soon as the first valid classification is
+matched. This occurs when the semantics of the identifier match and there is a
+valid option for the classification present in the ``.clang-tidy`` file - e.g.,
+``readability-identifier-naming.AbstractClassCase``.
+
+ - Typedef  ``[typedef]``
+ - TypeAlias  ``[using Alias = ...]``
+ - InlineNamespace ``[inline namespace]``
+ - Namespace ```[namespace]``
+ - <enum-members>
+   - ScopedEnumValue ``[enum class member]``
+   - EnumConstant  ``[enum member]``
+   - Constant
+   - Invalid
+ - <user-record-types>
+   - AbstractClass ``[class, struct, pure-virtual present]``
+   - Struct ``[struct]``
+   - Class ``[class, struct]``
+   - Struct ``[class]``
+   - Union ``[union]``
+   - Enum ``[enum, enum class]``
+   - Invalid
+ - <member-variables> - does not cover ``[static, constexpr]``
+   - ``[const]``
+     - ConstantMember
+     - Constant
+   - PrivateMember ``[private]``
+   - ProtectedMember ``[protected]``
+   - PublicMember ``[public]``
+   - Member
+   - Invalid
+ - <parameters>
+   - ConstexprVariable ``[constexpr]``
+   - ``[const]``
+     - ConstantPointerParameter ``[*]``
+     - ConstantParameter
+     - Constant
+   - ParameterPack ``[...]``
+   - PointerParameter ``[*]``
+   - Parameter
+   - Invalid
+ - <variable>
+   - ConstexprVariable ``[constexpr]``
+   - ``[const]``
+     - ClassConstant ``[const, static]``
+     - <file-level-variable>
+       - GlobalConstantPointer ``[const *]``
+       - GlobalConstant ``[const]``
+     - StaticConstant ``[static, const]``
+     - <local-variable>
+       - LocalConstantPointer ``[const *]``
+       - LocalConstant ``[const]``
+     - Constant ``[const]``
+   - <class-level>
+     - ClassMember ``[static]``
+   - <file-level-variable>
+     - GlobalPointer ``[*]``
+     - GlobalVariable
+   - <local-variable>
+     - StaticVariable ``[static]``
+     - LocalPointer ``[*]``
+     - LocalVariable
+   - <function/method-local-variable>
+     - LocalVariable
+   - Variable
+ - <class method>
+   - <ignore-base-class-method-overrides>
+   - ``[constexpr]``
+     - ConstexprMethod
+     - ConstexprFunction
+   - ClassMethod ``[static]``
+   - VirtualMethod ``[virtual]``
+   - PrivateMethod ``[private]``
+   - ProtectedMethod ``[protected]``
+   - PublicMethod ``[public]``
+   - Method
+   - Function
+   - Invalid
+ - <functions>
+   - <ignore ``main()``>
+   - ConstexprFunction ``[constexpr]``
+   - GlobalFunction ``[static method, static function, in any namespace]``
+   - Function
+   - Invalid
+ - <template parameter>
+   - <template-type-parameter>
+     - TypeTemplateParameter
+     - TemplateParameter
+     - Invalid
+   - <template-non-type-parameter>
+     - ValueTemplateParameter
+     - TemplateParameter
+     - Invalid
+   - <template-template-parameter>
+     - TemplateTemplateParameter
+     - TemplateParameter
+     - Invalid
+ - Invalid
+
+Labels listed in ``<>`` brackets are semantic qualifiers and attempt to
+illustrate the semantic context within which clang-tidy resolves the
+classification. These are not formal semantic labels, rather labels which
+attempt disambiguation within the context of this document. For example,
+``<member-variables>`` identifiers that clang tidy is currently looking only at
+member variables.
+
+Items in ``[]`` brackets provide C/C++ keywords and/or decorations relevant to
+that particular classification. These must be present in the declaration for
+clang-tidy to match the classification.
+
+List nesting is used to collate classifications which share some semantic
+identification - either a logical grouping using ``<>`` or ``[]`` qualifiers -
+and are each validated within that same semantic context. That is, all the
+classifications listed under ``<parameters>`` are each attempted in turn
+against anything identified as a parameter.
+
+The label ``Invalid`` indicates that valid classifications have been exhausted
+for a particular ``<semantic-context>`` and no further attempts will be made to
+classify the identifier in any other context. For example, in the 
+``<paramaters>`` semantic context, clang tidy will abort matching after failing
+to resolve the ``Parameter`` classification and a parameter will *not* be
+classified as a ``Variable``.
+
+Example classification
+----------------------
+
+The code snippet below[1]_ serves as an exhaustive example of various
+identifiers the ``readability-identifier-naming`` check is able to classify.
+Each identifier is documented with the list of classifications that apply to
+that identifier, listed in order of resolution. For example, a local pointer
+variable is commented ``// LocalPointer, LocalVariable, Variable`` indicating it
+is first classified as a ``LocalPointer``, then a ``LocalVariable`` and finally
+as a ``Variable``.
+
+.. code-block:: c++
+
+    #include <array>
+    #include <functional>
+    #include <iostream>
+    #include <string>
+
+    // MacroDefinition
+    #define MACRO_DEFINITION 42
+    // MacroDefinition
+    #define MACRO_FUNCTION(x) (void)x
+
+    // Typedef
+    typedef int MyArchaicInt;
+    // TypeAlias
+    using MyContemporaryInt = int;
+
+    // Namespace
+    namespace some_namespace
+    {
+    // InlineNamespace, Namespace
+    inline namespace version_1
+    {
+    }  // namespace version_1
+    }  // namespace some_namespace
+
+    // AbstractClass, Class, Struct
+    class AbstractClass
+    {
+    public:
+    // Not checked - constructors and destructors must match class name.
+    inline AbstractClass() = default;
+    // Not checked - constructors and destructors must match class name.
+    inline virtual ~AbstractClass() {}
+
+    // PublicMethod, Method, Function
+    void notAbstract();
+
+    // VirtualMethod, PublicMethod, Method, Function
+    virtual void abstractMethod() = 0;
+    };
+
+    // Class, Struct
+    class ClassNaming
+    {
+    // ----------------------
+    // Class member variables
+    // ----------------------
+    public:
+        // ConstexprVariable, ClassConstant, Constant, ClassMember, GlobalConstant, GlobalVariable, Variable
+        constexpr static int public_constexpr_member = 0;
+
+        // ConstantMember, Constant, PublicMember, Member
+        const int public_constant_member = 0;
+
+        // PublicMember, Member
+        int public_member = 0;
+
+        // ClassMember, Member, Variable
+        static int public_static_member;
+
+        // ClassConstant, Constant, GlobalConstant, GlobalVariable, Variable
+        static const int public_static_constant_member = 0;
+
+    protected:
+        // ConstexprVariable, ClassConstant, Constant, ClassMember, GlobalConstant, GlobalVariable, Variable
+        constexpr static int protected_constexpr_member = 0;
+
+        // ConstantMember, Constant, ProtectedMember, Member
+        const int protected_constant_member = 0;
+
+        // ProtectedMember, Member
+        int protected_member_ = 0;
+
+        // ClassMember, Member, Variable
+        static int protected_static_member;
+
+        // ClassConstant, Constant, GlobalConstant, GlobalVariable, Variable
+        static const int protected_static_constant_member = 0;
+
+    private:
+        // ConstexprVariable, ClassConstant, Constant, ClassMember, GlobalConstant, GlobalVariable, Variable
+        constexpr static int private_constexpr_member = 0;
+
+        // ConstantMember, Constant, PrivateMember, Member
+        const int private_constant_member_ = 0;
+
+        // PrivateMember, Member
+        int private_member_ = 0;
+
+        // ClassMember, Member, Variable
+        static int private_static_member;
+
+        // ClassConstant, Constant, GlobalConstant, GlobalVariable, Variable
+        static const int private_static_constant_member = 0;
+
+    // ----------------------
+    // Class methods
+    // ----------------------
+    public:
+        // ConstexprMethod, ConstexprFunction, PublicMethod, Method, Function
+        constexpr int publicConstexprFunc() { return 0; }
+
+        // ClassMethod, PublicMethod, Method, Function
+        static int publicStaticFunc() { return 0; }
+
+        // VirtualMethod, PublicMethod, Method, Function
+        virtual int publicFunc() { return 0; }
+
+    protected:
+        // ConstexprMethod, ConstexprFunction, ProtectedMethod, Method, Function
+        constexpr int protectedConstexprFunc() { return 0; }
+
+        // ClassMethod, ProtectedMethod, Method, Function
+        static int protectedStaticFunc() { return 0; }
+
+        // VirtualMethod, ProtectedMethod, Method, Function
+        virtual int protectedFunc() { return 0; }
+
+    private:
+        // ConstexprMethod, ConstexprFunction, PrivateMethod, Method, Function
+        constexpr int privateConstexprFunc() { return 0; }
+
+        // ClassMethod, PrivateMethod, Method, Function
+        static int privateStaticFunc() { return 0; }
+
+        // VirtualMethod, PrivateMethod, Method, Function
+        virtual int privateFunc() { return 0; }
+    };
+
+    // Static definitions provided for completeness.
+    int ClassNaming::public_static_member = 0;
+    int ClassNaming::protected_static_member = 0;
+    int ClassNaming::private_static_member = 0;
+
+    // Struct, Class
+    struct StructNaming
+    {
+    };
+
+    // Union
+    union UnionNaming
+    {
+        // PublicMember, Member
+        int union_variable = 0;
+    };
+
+    // Enum
+    enum class EnumClass
+    {
+        // ScopedEnumConstant, EnumConstant, Constant
+        EnumClassValue
+    };
+
+    // Enum
+    enum OldEnum
+    {
+        // EnumConstant, Constant
+        OLD_ENUM_VALUE
+    };
+
+    // GlobalFunction, Function
+    // @param str_ptr ConstantPointerParameter, ConstantParameter, PointerParameter, Parameter
+    // @param str ConstantParameter, Parameter
+    // @param ptr_param PointerParameter, Parameter
+    // @param param Parameter
+    int func(std::string *const str_ptr, const std::string &str, int *ptr_param, int param)
+    {
+        return 0;
+    }
+
+    // ---------
+    // Templates
+    // ---------
+
+    // Class, Struct
+    // @tparam Type TypeTemplateParameter, TemplateParameter
+    // @tparam Size ValueTemplateParameter, TemplateParameter
+    template <typename Type, int Size>
+    class ArrayTemplate
+    {
+    public:
+        // PublicMember, Member
+        Type bytes[Size];
+    };
+
+    // GlobalFunction, Function
+    // @tparam Param TypeTemplateParameter, TemplateParameter
+    // @param val Parameter
+    template <typename Param>
+    void templatePrint(const Param &val)
+    {
+        std::cout << val;
+    }
+
+    // GlobalFunction, Function
+    // @tparam Param TypeTemplateParameter, TemplateParameter
+    // @tparam Args TypeTemplateParameter, TemplateParameter
+    // @param val Parameter
+    // @param args ParameterPack, Parameter
+    template <typename Param, typename... Args>
+    void templatePrint(const Param &val, Args... args)
+    {
+        templatePrint(val);
+        std::cout << ' ';
+        templatePrint(args...);
+    }
+
+    // GlobalFunction, Function
+    // @tparam Callable TemplateTemplateParameter, TemplateParameter
+    // @tparam Param TypeTemplateParameter, TemplateParameter
+    // @param callable Parameter
+    // @param arg Parameter
+    template <template <typename> class Callable, typename Param>
+    Param templateTemplateParam(const Callable<Param(const Param &)> &callable, const Param &arg)
+    {
+        return callable(arg);
+    }
+
+    // -------------------------------
+    // Non-class variable declarations
+    // -------------------------------
+
+    // File level variables (global)
+    //
+    // The categorisation of anonymous namespace and named namespace variables is the same as for the global variable
+    // declarations below.
+
+    // ConstexprVariable, GlobalConstant, Constant, GlobalVariable, Variable
+    constexpr int global_constexpr = 0;
+
+    // GlobalConstantPointer, GlobalConstant, Constant, GlobalPointer, GlobalVariable, Variable
+    int *const global_const_ptr = nullptr;
+
+    // GlobalConstant, Constant, GlobalVariable, Variable
+    const int global_const = 0;
+
+    // GlobalConstant, [StaticConstant,] Constant, GlobalVariable, Variable
+    //
+    // StaticConstant does not actually trip for this declaration despite the documentation indicating that it should.
+    // StaticConstant does not appear to trip for anything. Reading the code, it seems that StaticConstant logic is in the
+    // wrong place and the conditions cannot be met.
+    static const int global_static_const = 0;
+
+    // GlobalConstantPointer, GlobalConstant, [StaticConstant,] Constant, GlobalPointer, GlobalVariable, Variable
+    //
+    // See @c global_static_const regarding StaticConstant
+    static int *const global_static_const_ptr = 0;
+
+    // GlobalFunction, Function
+    //
+    // @param seed Parameter
+    int varFunc(int seed = 0)
+    {
+        // ConstexprVariable, LocalConstant, Constant, LocalVariable, Variable
+        constexpr int local_constexpr = 0;
+
+        // LocalConstant, Constant, LocalVariable, Variable
+        const int local_const = 0;
+
+        // LocalConstantPointer, LocalConstant, Constant, LocalPointer, LocalVariable, Variable
+        const int *const local_const_ptr = &local_const;
+
+        // LocalConstant, Constant, LocalVariable, Variable
+        const auto local_lambda = [](int value) { return value; };
+
+        // StaticVariable, LocalVariable, Variable
+        static int static_variable = 0;
+
+        // LocalVariable, Variable
+        int local_variable = seed;
+
+        // LocalPointer, LocalVariable, Variable
+        int *local_variable_ptr = &local_variable;
+
+        return local_lambda(local_constexpr + local_const + *local_const_ptr + static_variable + local_variable +
+                            *local_variable_ptr);
+    }
+
+    // -------------------------------
+    // Non-class function declarations
+    // -------------------------------
+
+    // ConstexprFunction, GlobalFunction, Function
+    constexpr int answer()
+    {
+        return 42;
+    }
+
+    // GlobalFunction, Function
+    static int staticFunc()
+    {
+        return 0;
+    }
+
+    namespace
+    {
+    // Function
+    //
+    // Not a GlobalFunction since it is in a namespace.
+    int anonymousFunc()
+    {
+        return 0;
+    }
+    }  // namespace
+
+    // GlobalFunction, Function
+    int otherFunc()
+    {
+        return 0;
+    }
+
+.. [1] Source https://gist.github.com/KazNX/693761f2ee7881c120d209f04084e98a