Add new check in google module for Objective-C code to ensure global variables follow the naming convention of Google Objective-C Style Guide

[Wizard]

Summary

This is a new checker for objc files in clang-tidy.

The new check finds global variable declarations in Objective-C files that are not follow the pattern of variable names in Google's Objective-C Style Guide.

All the global variables should follow the pattern of "g[A-Z].*" (variables) or "k[A-Z].*" (constants). The check will suggest a variable name that follows the pattern
if it can be inferred from the original name.

[Eugene.Zelenko]

Check is really identifiers naming, so should have name like readability-identifier-naming. There are also google submodules, like google-readability, google-runtime, so will be good idea to add submodule for Objective-C.

docs/ReleaseNotes.rst

63

No need for module name.

[Wizard]

update the check name to indicate that it is objc specific

[hokein]

clang-tidy/google/GlobalVariableDeclarationCheck.cpp

26

Please make sure the patch follow the LLVM code style (https://llvm.org/docs/CodingStandards.html#name-types-functions-variables-and-enumerators-properly).

For variable names, LLVM also uses Camel Case.

29

Can you add a test for this case?

39

Instead of constructing the new prefix, maybe construct a full new name, and replace the old name, this would also simplify the code below (so that you can use decl-getSourceRange).

52

I think we need to filter out the source files, only allow the check to run on object-c files. You can use getLangOpts().

54

Do we need to restrict to variable definitions (IsDefinition())?

69

nit: I would use

if (const auto* VD = Result.Result.Nodes.getNodeAs<VarDecl>("global_var")) {
   ...
}
if (const auto* VD = XXX) {
   ...
}

clang-tidy/google/GoogleTidyModule.cpp

40

We should put the check under clang::tidy::google::objc namespace.

41

nit: sort in an alphabet order.

docs/clang-tidy/checks/google-global-variable-declaration.rst

7

nit: would be nicer provide the link.

docs/clang-tidy/checks/google-objc-global-variable-declaration.rst

4 ↗

(On Diff #120771)

nit: add missing ===

30 ↗

(On Diff #120771)

I think we should have a newline at the end of the file, the same to the test.m file.

test/clang-tidy/google-global-variable-declaration.m

6

nit: check the full code statement for fixes: static NSString* const kMConstString = @"hello";.

8

Maybe add a test without static?

[Wizard]

clang-tidy/google/GlobalVariableDeclarationCheck.cpp

29

The test case of single character is added in line 12 of google-objc-global-variable-declaration.m

54

I have thought about it. I think we should include non-definitions as well for now in order to check all cases.

[Wizard]

address comments

[Wizard]

clang-tidy/google/GlobalVariableDeclarationCheck.cpp

39

Done. But I played with it a little bit and had to avoid using decl-getSourceRange.
This method will return a range from the start of the type to the beginning of the init. E.g. for "static NSString* MyString = @"hi";" the substring of range will be "static NSString* MyString = @". It is pretty weird and will lead a result of replacement like 'kMyString"hi"'. With getLocation() + getName().size() it works well.

52

I took a look at the getLangOpts(), but did not find any straight stuff to get the language type. Is there any trick about this?

[hokein]

clang-tidy/google/GlobalVariableDeclarationCheck.cpp

29

There are still some code-style violations, e.g. fc, sc, the variable name should be CamelCase.

nit: I would use char here to make the type explicit.

30

I'm a bit unclear here, are these exceptions? Are they stated in the code-style guideline?

39

Oh, my bad. Thank for the clarification.

But still, we can use token range, CreateReplace(CharSourceRange::getTokenRange(SourceRange(Decl->getLocation()))) should work.

52

The members are defined in llvm/tools/clang/include/clang/Basic/LangOptions.def. getLangOpts().ObjC1() or getLangOpts().ObjC2() should work (not sure the difference between ObjC1 and ObjC2).

54

If this is expected, probably add a test case for it.

docs/clang-tidy/checks/google-objc-global-variable-declaration.rst

10 ↗

(On Diff #120914)

nit: please use the public link: http://google.github.io/styleguide/objcguide.html#variable-names

24 ↗

(On Diff #120914)

The prefix of fix should be g, right? becasue this is not a constant.

test/clang-tidy/google-objc-global-variable-declaration.m

18 ↗

(On Diff #120914)

Maybe use CHECK-FIXES: static NSString* a = @"too simple"; to make sure the check doesn't generate replacement., the same to the below case.

[Wizard]

Address comments. Adding language option check

[Wizard]

clang-tidy/google/GlobalVariableDeclarationCheck.cpp

30

Generally we should never use a single-character name for global variables (it does not match our regex in the check of course). The special check here is because we don't wanna give a false hint that it should be 'kA' or something. The user need to decide a better name on their own.

[hokein]

Thanks for the updates. The code looks mostly good, a few nits.

clang-tidy/google/GlobalVariableDeclarationCheck.cpp

30

I see. it is worth a comment describing the purpose here.

45

any reason why not using CharSourceRange::getTokenRange(SourceRange(Decl->getLocation())) here? Doesn't it work?

73

nit: Not sure whether it is worth here, but I'd just remove it.

docs/clang-tidy/checks/google-objc-global-variable-declaration.rst

19 ↗

(On Diff #121367)

nit: would be nicer to add a constant case here.

test/clang-tidy/google-objc-global-variable-declaration.m

22 ↗

(On Diff #121367)

Check the full code statement.

[Wizard]

address comments

[Wizard]

clang-tidy/google/GlobalVariableDeclarationCheck.cpp

45

Oh it works. I was looking at another constructor. So the getTokenRange can infer the length of the token given only the start location of the token?

[hokein]

LGTM.

clang-tidy/google/GlobalVariableDeclarationCheck.cpp

45

yes, it returns the range of the token which the source location points to.

clang-tidy/google/CMakeLists.txt

 set(LLVM_LINK_COMPONENTS support)
 
 add_clang_library(clangTidyGoogleModule
   AvoidCStyleCastsCheck.cpp
   DefaultArgumentsCheck.cpp
   ExplicitConstructorCheck.cpp
   ExplicitMakePairCheck.cpp
   GlobalNamesInHeadersCheck.cpp
+  GlobalVariableDeclarationCheck.cpp
   GoogleTidyModule.cpp
   IntegerTypesCheck.cpp
   NonConstReferences.cpp
   OverloadedUnaryAndCheck.cpp
   StringReferenceMemberCheck.cpp
   TodoCommentCheck.cpp
   UnnamedNamespaceInHeaderCheck.cpp
   UsingNamespaceDirectiveCheck.cpp

clang-tidy/google/GlobalVariableDeclarationCheck.h

+//===--- GlobalVariableDeclarationCheck.h - clang-tidy-----------*- C++ -*-===//
+//
+//                     The LLVM Compiler Infrastructure
+//
+// This file is distributed under the University of Illinois Open Source
+// License. See LICENSE.TXT for details.
+//
+//===----------------------------------------------------------------------===//
+
+#ifndef LLVM_CLANG_TOOLS_EXTRA_CLANG_TIDY_GOOGLE_GLOBAL_VARIABLE_DECLARATION_H
+#define LLVM_CLANG_TOOLS_EXTRA_CLANG_TIDY_GOOGLE_GLOBAL_VARIABLE_DECLARATION_H
+
+#include "../ClangTidy.h"
+
+namespace clang {
+namespace tidy {
+namespace google {
+
+/// The check for Objective-C global variables and constants naming convention.
+/// The declaration should follow the patterns of 'k[A-Z].*' (constants) or
+/// 'g[A-Z].*' (variables).
+///
+/// For the user-facing documentation see:
+/// http://clang.llvm.org/extra/clang-tidy/checks/google-global-variable-declaration.html
+class GlobalVariableDeclarationCheck : public ClangTidyCheck {
+public:
+  GlobalVariableDeclarationCheck(StringRef Name, ClangTidyContext *Context)
+      : ClangTidyCheck(Name, Context) {}
+  void registerMatchers(ast_matchers::MatchFinder *Finder) override;
+  void check(const ast_matchers::MatchFinder::MatchResult &Result) override;
+};
+
+} // namespace google
+} // namespace tidy
+} // namespace clang
+
+#endif // LLVM_CLANG_TOOLS_EXTRA_CLANG_TIDY_GOOGLE_GLOBAL_VARIABLE_DECLARATION_H

clang-tidy/google/GlobalVariableDeclarationCheck.cpp

+//===--- GlobalVariableDeclarationCheck.cpp - clang-tidy-------------------===//
+//
+//                     The LLVM Compiler Infrastructure
+//
+// This file is distributed under the University of Illinois Open Source
+// License. See LICENSE.TXT for details.
+//
+//===----------------------------------------------------------------------===//
+
+#include "GlobalVariableDeclarationCheck.h"
+#include "clang/AST/ASTContext.h"
+#include "clang/ASTMatchers/ASTMatchFinder.h"
+#include "llvm/ADT/StringExtras.h"
+#include "llvm/ADT/StringRef.h"
+
+#include <string>
+
+using namespace clang::ast_matchers;
+
+namespace clang {
+namespace tidy {
+namespace google {
+
+namespace {
+
+FixItHint generateFixItHint(const VarDecl *decl, bool isConst) {
+  auto fc = decl->getName()[0];
+  if (!llvm::isAlpha(fc) || decl->getName().size() == 1) {
+    // No fix available if first character is not alphabetical character, or it
+    // is a single-character variable.
+    return FixItHint();
+  }
+  auto sc = decl->getName()[1];
+  if ((fc == 'k' || fc == 'g') && !llvm::isAlpha(sc)) {
+    // No fix available if the prefix is correct but the second character is not
+    // alphabetical.
+    return FixItHint();
+  }
+  auto prefix =
+      (isConst ? "k" : "g") + llvm::StringRef(std::string(1, fc)).upper();
+  return FixItHint::CreateReplacement(
+      CharSourceRange(SourceRange(decl->getLocation(),
+                                  decl->getLocation().getLocWithOffset(1)),
+                      false),
+      llvm::StringRef(prefix));
+}
+}  // namespace
+
+void GlobalVariableDeclarationCheck::registerMatchers(MatchFinder *Finder) {
+  // need to add two matchers since we need to bind different ids to distinguish
+  // constants and variables. Since bind() can only be called on node matchers,
+  // we cannot make it in one matcher.
+  Finder->addMatcher(
+      varDecl(hasGlobalStorage(), unless(hasType(isConstQualified())),
+              unless(matchesName("::g[A-Z]")))
+          .bind("global_var"),
+      this);
+  Finder->addMatcher(varDecl(hasGlobalStorage(), hasType(isConstQualified()),
+                             unless(matchesName("::k[A-Z]")))
+                         .bind("global_const"),
+                     this);
+}
+
+void GlobalVariableDeclarationCheck::check(
+    const MatchFinder::MatchResult &Result) {
+  const auto *variableDecl = Result.Nodes.getNodeAs<VarDecl>("global_var");
+  const auto *constantDecl = Result.Nodes.getNodeAs<VarDecl>("global_const");
+  assert(variableDecl != nullptr || constantDecl != nullptr);
+  if (variableDecl != nullptr) {
+    diag(variableDecl->getLocation(),
+         "non-const global variable '%0' must have a name which starts with "
+         "'g[A-Z]'")
+        << variableDecl->getName() << generateFixItHint(variableDecl, false);
+  }
+  if (constantDecl != nullptr) {
+    diag(constantDecl->getLocation(),
+         "const global variable '%0' must have a name which starts with "
+         "'k[A-Z]'")
+        << constantDecl->getName() << generateFixItHint(constantDecl, true);
+  }
+}
+
+}  // namespace google
+}  // namespace tidy
+}  // namespace clang

clang-tidy/google/GoogleTidyModule.cpp

 #include "../readability/FunctionSizeCheck.h"
 #include "../readability/NamespaceCommentCheck.h"
 #include "../readability/RedundantSmartptrGetCheck.h"
 #include "AvoidCStyleCastsCheck.h"
 #include "DefaultArgumentsCheck.h"
 #include "ExplicitConstructorCheck.h"
 #include "ExplicitMakePairCheck.h"
 #include "GlobalNamesInHeadersCheck.h"
+#include "GlobalVariableDeclarationCheck.h"
 #include "IntegerTypesCheck.h"
 #include "NonConstReferences.h"
 #include "OverloadedUnaryAndCheck.h"
 #include "StringReferenceMemberCheck.h"
 #include "TodoCommentCheck.h"
 #include "UnnamedNamespaceInHeaderCheck.h"
 #include "UsingNamespaceDirectiveCheck.h"
 
 using namespace clang::ast_matchers;
 
 namespace clang {
 namespace tidy {
 namespace google {
 
 class GoogleModule : public ClangTidyModule {
 public:
   void addCheckFactories(ClangTidyCheckFactories &CheckFactories) override {
+    CheckFactories.registerCheck<GlobalVariableDeclarationCheck>(
+        "google-global-variable-declaration");
     CheckFactories.registerCheck<build::ExplicitMakePairCheck>(
         "google-build-explicit-make-pair");
     CheckFactories.registerCheck<build::UnnamedNamespaceInHeaderCheck>(
         "google-build-namespaces");
     CheckFactories.registerCheck<build::UsingNamespaceDirectiveCheck>(
         "google-build-using-namespace");
     CheckFactories.registerCheck<DefaultArgumentsCheck>(
         "google-default-arguments");

docs/ReleaseNotes.rst

 Improvements to clang-rename
 ----------------------------
 
 The improvements are...
 
 Improvements to clang-tidy
 --------------------------
 
+- New `google-global-variable-declaration
+  <http://clang.llvm.org/extra/clang-tidy/checks/google-global-variable-declaration.html>`_ check
+
+  Add new check in google module for Objective-C code to ensure global 
+  variables follow the naming convention of 'k[A-Z].*' (for constants) 
+  or 'g[A-Z].*' (for variables).
+
 - New module `objc` for Objective-C style checks.
 
 - New `objc-forbidden-subclassing
   <http://clang.llvm.org/extra/clang-tidy/checks/objc-forbidden-subclassing.html>`_ check
 
   Ensures Objective-C classes do not subclass any classes which are
   not intended to be subclassed.
 

docs/clang-tidy/checks/google-global-variable-declaration.rst

+.. title:: clang-tidy - google-global-variable-declaration
+
+google-global-variable-declaration
+==================================
+
+Finds global variable declarations in Objective-C files that are not follow the pattern
+of variable names in Google's Objective-C Style Guide.
+
+All the global variables should follow the pattern of `g[A-Z].*` (variables) or
+`k[A-Z].*` (constants). The check will suggest a variable name that follows the pattern
+if it can be inferred from the original name.
+
+For code:
+
+.. code-block:: objc
+  static NSString* myString = @"hello";
+
+The fix will be:
+
+.. code-block:: objc
+  static NSString* kMyString = @"hello";
+
+However for code that prefixed with non-alphabetical characters like:
+
+.. code-block:: objc
+  static NSString* __anotherString = @"world";
+
+The check will give a warning message but will not be able to suggest a fix. The user
+need to fix it on his own.
 No newline at end of file

docs/clang-tidy/checks/list.rst

.. toctree::
    cppcoreguidelines-slicing
    cppcoreguidelines-special-member-functions
    google-build-explicit-make-pair
    google-build-namespaces
    google-build-using-namespace
    google-default-arguments
    google-explicit-constructor
    google-global-names-in-headers
+   google-global-variable-declaration
    google-readability-braces-around-statements (redirects to readability-braces-around-statements) <google-readability-braces-around-statements>
    google-readability-casting
    google-readability-function-size (redirects to readability-function-size) <google-readability-function-size>
    google-readability-namespace-comments (redirects to llvm-namespace-comment) <google-readability-namespace-comments>
    google-readability-redundant-smartptr-get (redirects to readability-redundant-smartptr-get) <google-readability-redundant-smartptr-get>
    google-readability-todo
    google-runtime-int
    google-runtime-member-string-references

test/clang-tidy/google-global-variable-declaration.m

+// RUN: %check_clang_tidy %s google-global-variable-declaration %t
+
+@class NSString;
+static NSString* const myConstString = @"hello";
+// CHECK-MESSAGES: :[[@LINE-1]]:24: warning: const global variable 'myConstString' must have a name which starts with 'k[A-Z]' [google-global-variable-declaration]
+// CHECK-FIXES: kMyConstString
+
+static NSString* MyString = @"hi";
+// CHECK-MESSAGES: :[[@LINE-1]]:18: warning: non-const global variable 'MyString' must have a name which starts with 'g[A-Z]' [google-global-variable-declaration]
+// CHECK-FIXES: gMyString
+
+static NSString* a = @"too simple";
+// CHECK-MESSAGES: :[[@LINE-1]]:18: warning: non-const global variable 'a' must have a name which starts with 'g[A-Z]' [google-global-variable-declaration]
+// CHECK-FIXES-NOT: gA
+
+static NSString* const _notAlpha = @"NotBeginWithAlpha";
+// CHECK-MESSAGES: :[[@LINE-1]]:24: warning: const global variable '_notAlpha' must have a name which starts with 'k[A-Z]' [google-global-variable-declaration]
+// CHECK-FIXES-NOT: k_notAlpha
+
+static NSString* const k_Alpha = @"SecondNotAlpha";
+// CHECK-MESSAGES: :[[@LINE-1]]:24: warning: const global variable 'k_Alpha' must have a name which starts with 'k[A-Z]' [google-global-variable-declaration]
+// CHECK-FIXES-NOT: kK_Alpha
+
+static NSString* const kGood = @"hello";
+// CHECK-MESSAGES-NOT: :[[@LINE-1]]:24: warning: const global variable 'kGood' must have a name which starts with 'k[A-Z]' [google-global-variable-declaration]
+static NSString* gMyIntGood = 0;
+// CHECK-MESSAGES-NOT: :[[@LINE-1]]:18: warning: non-const global variable 'gMyIntGood' must have a name which starts with 'g[A-Z]' [google-global-variable-declaration]
+@implementation Foo
+- (void)f {
+    int x = 0;
+// CHECK-MESSAGES-NOT: :[[@LINE-1]]:9: warning: non-const global variable 'gMyIntGood' must have a name which starts with 'g[A-Z]' [google-global-variable-declaration]
+}
+@end
 No newline at end of file