[clang-tidy] Add cppcoreguidelines-avoid-const-or-ref-data-members check

[carlosgalvezp]

Summary

Flags uses of const-qualified and reference data members in structs.
Implements rule C.12 of C++ Core Guidelines.

[carlosgalvezp]

Fix FIXME

[carlosgalvezp]

Move logic from check to registerMatchers

[dfrib]

clang-tools-extra/test/clang-tidy/checkers/cppcoreguidelines-avoid-const-or-ref-data-members.cpp

25 ↗

(On Diff #433757)

Differentiate between lvalue reference and rvalue reference members using these terms instead of "ref" and "refref". E.g.:

• RefMember -> LvalueRefMember
• RefRefMember -> RvalueRefMember

(apply to all cases below).

40 ↗

(On Diff #433757)

ConstAndRefMembers

100 ↗

(On Diff #433757)

Should we test for array types also? E.g.:

template<int N> using Array = int[N];

struct ConstArrayMember {
  const Array<1> c;
};

struct LvalueRefArrayMember {
  Array<2>& lvr;   
};

struct ConstRefArrayMember {
  Array<3> const& clvr;
};

struct LvalueRefArrayMember {
  Array<4>&& rvr;   
};

121 ↗

(On Diff #433757)

Consider expanding with the the non-const lvalue ref case, e.g.

TemplatedOk<int> t4{};
TemplateRef<int&> t5{t4.t};

[carlosgalvezp]

Fix review comments

[carlosgalvezp]

This comment was removed by carlosgalvezp.

[Eugene.Zelenko]

clang-tools-extra/clang-tidy/cppcoreguidelines/AvoidConstOrRefDataMembersCheck.h

30

Please add isLanguageVersionSupported.

clang-tools-extra/docs/clang-tidy/checks/cppcoreguidelines-avoid-const-or-ref-data-members.rst

10 ↗

(On Diff #433989)

Usually such links are placed at the end.

[carlosgalvezp]

Address review comments.
Rebase on latest main.

clang-tools-extra/clang-tidy/cppcoreguidelines/AvoidConstOrRefDataMembersCheck.h

30

Done. I generated this check via add_new_check.py - should we add this there as well to avoid similar issues in the future (separate commit)?

I see some checks implement this function and some others don't, so it's not totally clear to me when is needed.

[carlosgalvezp]

Remove copy-paste comment

[carlosgalvezp]

Kind ping to reviewers :)

[LegalizeAdulthood]

Tests and docs have moved to subdirectories by module name.

Please rebase onto HEAD and:

• move test/clang-tidy/checkers/cppcoreguidelines-avoid-const-or-ref-data-members.cpp to test/clang-tidy/checkers/cppcoreguidelines/avoid-const-or-ref-data-members.cpp
• move docs/clang-tidy/checks/cppcoreguidelines-avoid-const-or-ref-data-members.rst to docs/clang-tidy/checks/cppcoreguidelines/avoid-const-or-ref-data-members.rst
• make the target test-clang-extra to validate your tests still pass
• make the target docs-clang-tools-html to validate your documentation links are correct

[carlosgalvezp]

Rebase and fix directory structure for doc and test.

[carlosgalvezp]

Fix test name

[carlosgalvezp]

@LegalizeAdulthood I've addressed your comments, thanks for the clear instructions! One thing I didn't manage to do is build the target docs-clang-tools-html, it says it doesn't exist. I've enabled LLVM_BUILD_DOCS=ON in the CMake call - do you know if I need to enable something else?

PS: also the test-clang-extra doesn't exist, I typically run check-clang-tools-extra.

[LegalizeAdulthood]

clang-tools-extra/docs/ReleaseNotes.rst

102

Sort new checks by check name.

103

This link is wrong, please install Sphinx and build the target docs-clang-tools-html to validate links

[carlosgalvezp]

Address review comments.

[carlosgalvezp]

@LegalizeAdulthood Thanks for the review! I've now rebased and addressed your comments. I've also verify the docs with the command you suggested, I was missing -DLLVM_ENABLE_SPHINX in the cmake command.

[carlosgalvezp]

@LegalizeAdulthood I've addressed your comments, is there anything else that should be fixed before landing the patch?

[carlosgalvezp]

• Rebase onto latest main.
• Remove references to std::reference_wrapper as alternative suggestions, as per: https://github.com/isocpp/CppCoreGuidelines/issues/1919

[carlosgalvezp]

Ping to reviewers

[carlosgalvezp]

Rebase onto latest main.

[carlosgalvezp]

@njames93 Would you mind reviewing? Thanks!

[njames93]

clang-tools-extra/test/clang-tidy/checkers/cppcoreguidelines/avoid-const-or-ref-data-members.cpp

104–105

I feel like this could potentially confuse users. Maybe we should walk the alias to show where the type was declared to be const/reference.
Or, not a fan of this choice, don't diagnose these unless the user opts into this behaviour.

137–158

This whole block displeases me. Warning on the instantiation isn't a great idea and could confuse users.
Would again need some expansion notes to explain why the warning is being triggered, especially when if for 99% of the uses one of these structs has a T which isn't const or a reference.
Failing that just disabling the check in template instantiations would also fix the issue.

[carlosgalvezp]

Great feedback, thanks! I had some ideas on how to go around the issues, looking forward to your thoughts.

clang-tools-extra/test/clang-tidy/checkers/cppcoreguidelines/avoid-const-or-ref-data-members.cpp

104–105

Sounds reasonable! I see that Clang compiler does not print an "alias stack" in detail, for example here:

https://godbolt.org/z/8sqE4fM1v

For the sake of consistency and simplicity, would it make sense to print something similar here? Example:

"warning: member 'c' of type 'ConstType' (aka 'const int') is const qualified"

137–158

I agree with the sentiment 100%. Unfortunately it's currently the only way to test this kind of code in clang-tidy AFAIK, see for example other existing checks:

https://github.com/llvm/llvm-project/blob/main/clang-tools-extra/test/clang-tidy/checkers/google/readability-casting.cpp#L332

I fully agree on needing expansion notes, just like the Clang compiler does. A very similar question about it was recently posted:

https://discourse.llvm.org/t/clang-tidy-diagnostics-for-template-code/62909

In that sense I believe it would make sense to try and focus the efforts into implementing a good centralized solution instead of having it duplicated on different checks.

Until then, I believe it should be fairly easy to clarify the actual type as proposed in the above comment for aliases.

What do you think?

[carlosgalvezp]

• Display type information in the diagnostic.
• Rebase onto latest main.

[carlosgalvezp]

@njames93 I've updated the patch with extra type information, let me know if you think it's good enough!

[carlosgalvezp]

@njames93 Friendly ping.

[carlosgalvezp]

Rebase

[bigdavedev]

LGTM. All comments have been addressed. Any improvements to the diagnostics can be made down the line depending on how users feel about them.

clang-tools-extra/clang-tidy/cppcoreguidelines/AvoidConstOrRefDataMembersCheck.h

+//===--- AvoidConstOrRefDataMembersCheck.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_CPPCOREGUIDELINES_AVOIDCONSTORREFDATAMEMBERSCHECK_H
+#define LLVM_CLANG_TOOLS_EXTRA_CLANG_TIDY_CPPCOREGUIDELINES_AVOIDCONSTORREFDATAMEMBERSCHECK_H
+
+#include "../ClangTidyCheck.h"
+
+namespace clang {
+namespace tidy {
+namespace cppcoreguidelines {
+
+/// Const-qualified or reference data members in classes should be avoided, as
+/// they make the class non-copy-assignable.
+///
+/// For the user-facing documentation see:
+/// http://clang.llvm.org/extra/clang-tidy/checks/cppcoreguidelines/avoid-const-or-ref-data-members.html
+class AvoidConstOrRefDataMembersCheck : public ClangTidyCheck {
+public:
+  AvoidConstOrRefDataMembersCheck(StringRef Name, ClangTidyContext *Context)
+      : ClangTidyCheck(Name, Context) {}
+  bool isLanguageVersionSupported(const LangOptions &LangOpts) const override {
+    return LangOpts.CPlusPlus;
+  }
+  void registerMatchers(ast_matchers::MatchFinder *Finder) override;
+  void check(const ast_matchers::MatchFinder::MatchResult &Result) override;
+};
+
+} // namespace cppcoreguidelines
+} // namespace tidy
+} // namespace clang
+
+#endif // LLVM_CLANG_TOOLS_EXTRA_CLANG_TIDY_CPPCOREGUIDELINES_AVOIDCONSTORREFDATAMEMBERSCHECK_H

clang-tools-extra/clang-tidy/cppcoreguidelines/AvoidConstOrRefDataMembersCheck.cpp

+//===--- AvoidConstOrRefDataMembersCheck.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 "AvoidConstOrRefDataMembersCheck.h"
+#include "clang/AST/ASTContext.h"
+#include "clang/ASTMatchers/ASTMatchFinder.h"
+
+using namespace clang::ast_matchers;
+
+namespace clang {
+namespace tidy {
+namespace cppcoreguidelines {
+
+void AvoidConstOrRefDataMembersCheck::registerMatchers(MatchFinder *Finder) {
+  Finder->addMatcher(
+      fieldDecl(hasType(hasCanonicalType(referenceType()))).bind("ref"), this);
+  Finder->addMatcher(
+      fieldDecl(hasType(qualType(isConstQualified()))).bind("const"), this);
+}
+
+void AvoidConstOrRefDataMembersCheck::check(
+    const MatchFinder::MatchResult &Result) {
+  if (const auto *MatchedDecl = Result.Nodes.getNodeAs<FieldDecl>("ref"))
+    diag(MatchedDecl->getLocation(), "member %0 of type %1 is a reference")
+        << MatchedDecl << MatchedDecl->getType();
+  if (const auto *MatchedDecl = Result.Nodes.getNodeAs<FieldDecl>("const"))
+    diag(MatchedDecl->getLocation(), "member %0 of type %1 is const qualified")
+        << MatchedDecl << MatchedDecl->getType();
+}
+
+} // namespace cppcoreguidelines
+} // namespace tidy
+} // namespace clang

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

 set(LLVM_LINK_COMPONENTS
   FrontendOpenMP
   Support
   )
 
 add_clang_library(clangTidyCppCoreGuidelinesModule
+  AvoidConstOrRefDataMembersCheck.cpp
   AvoidGotoCheck.cpp
   AvoidNonConstGlobalVariablesCheck.cpp
   CppCoreGuidelinesTidyModule.cpp
   InitVariablesCheck.cpp
   InterfacesGlobalInitCheck.cpp
   MacroUsageCheck.cpp
   NarrowingConversionsCheck.cpp
   NoMallocCheck.cpp

clang-tools-extra/clang-tidy/cppcoreguidelines/CppCoreGuidelinesTidyModule.cpp

 //===-- CppCoreGuidelinesTidyModule.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 "../ClangTidy.h"
 #include "../ClangTidyModule.h"
 #include "../ClangTidyModuleRegistry.h"
 #include "../misc/NonPrivateMemberVariablesInClassesCheck.h"
 #include "../misc/UnconventionalAssignOperatorCheck.h"
 #include "../modernize/AvoidCArraysCheck.h"
 #include "../modernize/UseOverrideCheck.h"
 #include "../readability/MagicNumbersCheck.h"
+#include "AvoidConstOrRefDataMembersCheck.h"
 #include "AvoidGotoCheck.h"
 #include "AvoidNonConstGlobalVariablesCheck.h"
 #include "InitVariablesCheck.h"
 #include "InterfacesGlobalInitCheck.h"
 #include "MacroUsageCheck.h"
 #include "NarrowingConversionsCheck.h"
 #include "NoMallocCheck.h"
 #include "OwningMemoryCheck.h"

 namespace cppcoreguidelines {
 
 /// A module containing checks of the C++ Core Guidelines
 class CppCoreGuidelinesModule : public ClangTidyModule {
 public:
   void addCheckFactories(ClangTidyCheckFactories &CheckFactories) override {
     CheckFactories.registerCheck<modernize::AvoidCArraysCheck>(
         "cppcoreguidelines-avoid-c-arrays");
+    CheckFactories.registerCheck<AvoidConstOrRefDataMembersCheck>(
+        "cppcoreguidelines-avoid-const-or-ref-data-members");
     CheckFactories.registerCheck<AvoidGotoCheck>(
         "cppcoreguidelines-avoid-goto");
     CheckFactories.registerCheck<readability::MagicNumbersCheck>(
         "cppcoreguidelines-avoid-magic-numbers");
     CheckFactories.registerCheck<AvoidNonConstGlobalVariablesCheck>(
         "cppcoreguidelines-avoid-non-const-global-variables");
     CheckFactories.registerCheck<modernize::UseOverrideCheck>(
         "cppcoreguidelines-explicit-virtual-functions");

clang-tools-extra/docs/ReleaseNotes.rst

 The improvements are...
 
 Improvements to clang-tidy
 --------------------------
 
 New checks
 ^^^^^^^^^^
 
+- New :doc:`cppcoreguidelines-avoid-const-or-ref-data-members
+  <clang-tidy/checks/cppcoreguidelines/avoid-const-or-ref-data-members>` check.
+
+  Warns when a struct or class uses const or reference (lvalue or rvalue) data members.
+
 New check aliases
 ^^^^^^^^^^^^^^^^^
 
 Changes in existing checks
 ^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 Removed checks
 ^^^^^^^^^^^^^^

clang-tools-extra/docs/clang-tidy/checks/cppcoreguidelines/avoid-const-or-ref-data-members.rst

+.. title:: clang-tidy - cppcoreguidelines-avoid-const-or-ref-data-members
+
+cppcoreguidelines-avoid-const-or-ref-data-members
+=================================================
+
+This check warns when structs or classes have const-qualified or reference
+(lvalue or rvalue) data members. Having such members is rarely useful, and
+makes the class only copy-constructible but not copy-assignable.
+
+Examples:
+
+.. code-block:: c++
+
+  // Bad, const-qualified member
+  struct Const {
+    const int x;
+  }
+
+  // Good:
+  class Foo {
+   public:
+    int get() const { return x; }
+   private:
+    int x;
+  };
+
+  // Bad, lvalue reference member
+  struct Ref {
+    int& x;
+  };
+
+  // Good:
+  struct Foo {
+    int* x;
+    std::unique_ptr<int> x;
+    std::shared_ptr<int> x;
+    gsl::not_null<int> x;
+  };
+
+  // Bad, rvalue reference member
+  struct RefRef {
+    int&& x;
+  };
+
+The check implements
+`rule C.12 of C++ Core Guidelines <https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md#c12-dont-make-data-members-const-or-references>`_.
+
+Further reading:
+`Data members: Never const <https://quuxplusone.github.io/blog/2022/01/23/dont-const-all-the-things/#data-members-never-const>`_.

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

.. csv-table::
    `clang-analyzer-osx.cocoa.MissingSuperCall <clang-analyzer/osx.cocoa.MissingSuperCall.html>`_,
    `clang-analyzer-osx.cocoa.NonNilReturnValue <clang-analyzer/osx.cocoa.NonNilReturnValue.html>`_,
    `clang-analyzer-osx.cocoa.RunLoopAutoreleaseLeak <clang-analyzer/osx.cocoa.RunLoopAutoreleaseLeak.html>`_,
    `clang-analyzer-valist.CopyToSelf <clang-analyzer/valist.CopyToSelf.html>`_,
    `clang-analyzer-valist.Uninitialized <clang-analyzer/valist.Uninitialized.html>`_,
    `clang-analyzer-valist.Unterminated <clang-analyzer/valist.Unterminated.html>`_,
    `concurrency-mt-unsafe <concurrency/mt-unsafe.html>`_,
    `concurrency-thread-canceltype-asynchronous <concurrency/thread-canceltype-asynchronous.html>`_,
+   `cppcoreguidelines-avoid-const-or-ref-data-members <cppcoreguidelines/avoid-const-or-ref-data-members.html>`_,
    `cppcoreguidelines-avoid-goto <cppcoreguidelines/avoid-goto.html>`_,
    `cppcoreguidelines-avoid-non-const-global-variables <cppcoreguidelines/avoid-non-const-global-variables.html>`_,
    `cppcoreguidelines-init-variables <cppcoreguidelines/init-variables.html>`_, "Yes"
    `cppcoreguidelines-interfaces-global-init <cppcoreguidelines/interfaces-global-init.html>`_,
    `cppcoreguidelines-macro-usage <cppcoreguidelines/macro-usage.html>`_,
    `cppcoreguidelines-narrowing-conversions <cppcoreguidelines/narrowing-conversions.html>`_,
    `cppcoreguidelines-no-malloc <cppcoreguidelines/no-malloc.html>`_,
    `cppcoreguidelines-owning-memory <cppcoreguidelines/owning-memory.html>`_,

clang-tools-extra/test/clang-tidy/checkers/cppcoreguidelines/avoid-const-or-ref-data-members.cpp

+// RUN: %check_clang_tidy %s cppcoreguidelines-avoid-const-or-ref-data-members %t
+namespace std {
+template <typename T>
+struct unique_ptr {};
+
+template <typename T>
+struct shared_ptr {};
+} // namespace std
+
+namespace gsl {
+template <typename T>
+struct not_null {};
+} // namespace gsl
+
+struct Ok {
+  int i;
+  int *p;
+  const int *pc;
+  std::unique_ptr<int> up;
+  std::shared_ptr<int> sp;
+  gsl::not_null<int> n;
+};
+
+struct ConstMember {
+  const int c;
+  // CHECK-MESSAGES: :[[@LINE-1]]:13: warning: member 'c' of type 'const int' is const qualified [cppcoreguidelines-avoid-const-or-ref-data-members]
+};
+
+struct LvalueRefMember {
+  int &lr;
+  // CHECK-MESSAGES: :[[@LINE-1]]:8: warning: member 'lr' of type 'int &' is a reference
+};
+
+struct ConstRefMember {
+  const int &cr;
+  // CHECK-MESSAGES: :[[@LINE-1]]:14: warning: member 'cr' of type 'const int &' is a reference
+};
+
+struct RvalueRefMember {
+  int &&rr;
+  // CHECK-MESSAGES: :[[@LINE-1]]:9: warning: member 'rr' of type 'int &&' is a reference
+};
+
+struct ConstAndRefMembers {
+  const int c;
+  // CHECK-MESSAGES: :[[@LINE-1]]:13: warning: member 'c' of type 'const int' is const qualified
+  int &lr;
+  // CHECK-MESSAGES: :[[@LINE-1]]:8: warning: member 'lr' of type 'int &' is a reference
+  const int &cr;
+  // CHECK-MESSAGES: :[[@LINE-1]]:14: warning: member 'cr' of type 'const int &' is a reference
+  int &&rr;
+  // CHECK-MESSAGES: :[[@LINE-1]]:9: warning: member 'rr' of type 'int &&' is a reference
+};
+
+struct Foo {};
+
+struct Ok2 {
+  Foo i;
+  Foo *p;
+  const Foo *pc;
+  std::unique_ptr<Foo> up;
+  std::shared_ptr<Foo> sp;
+  gsl::not_null<Foo> n;
+};
+
+struct ConstMember2 {
+  const Foo c;
+  // CHECK-MESSAGES: :[[@LINE-1]]:13: warning: member 'c' of type 'const Foo' is const qualified
+};
+
+struct LvalueRefMember2 {
+  Foo &lr;
+  // CHECK-MESSAGES: :[[@LINE-1]]:8: warning: member 'lr' of type 'Foo &' is a reference
+};
+
+struct ConstRefMember2 {
+  const Foo &cr;
+  // CHECK-MESSAGES: :[[@LINE-1]]:14: warning: member 'cr' of type 'const Foo &' is a reference
+};
+
+struct RvalueRefMember2 {
+  Foo &&rr;
+  // CHECK-MESSAGES: :[[@LINE-1]]:9: warning: member 'rr' of type 'Foo &&' is a reference
+};
+
+struct ConstAndRefMembers2 {
+  const Foo c;
+  // CHECK-MESSAGES: :[[@LINE-1]]:13: warning: member 'c' of type 'const Foo' is const qualified
+  Foo &lr;
+  // CHECK-MESSAGES: :[[@LINE-1]]:8: warning: member 'lr' of type 'Foo &' is a reference
+  const Foo &cr;
+  // CHECK-MESSAGES: :[[@LINE-1]]:14: warning: member 'cr' of type 'const Foo &' is a reference
+  Foo &&rr;
+  // CHECK-MESSAGES: :[[@LINE-1]]:9: warning: member 'rr' of type 'Foo &&' is a reference
+};
+
+using ConstType = const int;
+using RefType = int &;
+using ConstRefType = const int &;
+using RefRefType = int &&;
+
+struct WithAlias {
+  ConstType c;
+  // CHECK-MESSAGES: :[[@LINE-1]]:13: warning: member 'c' of type 'ConstType' (aka 'const int') is const qualified
+  RefType lr;
+  // CHECK-MESSAGES: :[[@LINE-1]]:11: warning: member 'lr' of type 'RefType' (aka 'int &') is a reference
+  ConstRefType cr;
+  // CHECK-MESSAGES: :[[@LINE-1]]:16: warning: member 'cr' of type 'ConstRefType' (aka 'const int &') is a reference
+  RefRefType rr;
+  // CHECK-MESSAGES: :[[@LINE-1]]:14: warning: member 'rr' of type 'RefRefType' (aka 'int &&') is a reference
+};
+
+template <int N>
+using Array = int[N];
+
+struct ConstArrayMember {
+  const Array<1> c;
+  // CHECK-MESSAGES: :[[@LINE-1]]:18: warning: member 'c' of type 'const Array<1>' (aka 'const int[1]') is const qualified
+};
+
+struct LvalueRefArrayMember {
+  Array<2> &lr;
+  // CHECK-MESSAGES: :[[@LINE-1]]:13: warning: member 'lr' of type 'Array<2> &' (aka 'int (&)[2]') is a reference
+};
+
+struct ConstLvalueRefArrayMember {
+  const Array<3> &cr;
+  // CHECK-MESSAGES: :[[@LINE-1]]:19: warning: member 'cr' of type 'const Array<3> &' (aka 'const int (&)[3]') is a reference
+};
+
+struct RvalueRefArrayMember {
+  Array<4> &&rr;
+  // CHECK-MESSAGES: :[[@LINE-1]]:14: warning: member 'rr' of type 'Array<4> &&' (aka 'int (&&)[4]') is a reference
+};
+
+template <typename T>
+struct TemplatedOk {
+  T t;
+};
+
+template <typename T>
+struct TemplatedConst {
+  T t;
+  // CHECK-MESSAGES: :[[@LINE-1]]:5: warning: member 't' of type 'const int' is const qualified
+};
+
+template <typename T>
+struct TemplatedConstRef {
+  T t;
+  // CHECK-MESSAGES: :[[@LINE-1]]:5: warning: member 't' of type 'const int &' is a reference
+};
+
+template <typename T>
+struct TemplatedRefRef {
+  T t;
+  // CHECK-MESSAGES: :[[@LINE-1]]:5: warning: member 't' of type 'int &&' is a reference
+};
+
+template <typename T>
+struct TemplatedRef {
+  T t;
+  // CHECK-MESSAGES: :[[@LINE-1]]:5: warning: member 't' of type 'int &' is a reference
+};
+
+TemplatedOk<int> t1{};
+TemplatedConst<const int> t2{123};
+TemplatedConstRef<const int &> t3{123};
+TemplatedRefRef<int &&> t4{123};
+TemplatedRef<int &> t5{t1.t};