[clang-tidy] implement check for goto

[JonasToth]

Summary

The usage of goto is discourage in C++ since forever. This check implements
a warning for every goto. Even though there are (rare) valid use cases for
goto, better high level constructs should be used.

goto is used sometimes in C programs to free resources at the end of
functions in the case of errors. This pattern is better implemented with
RAII in C++.

[JonasToth]

• fix typos and return type of main in test

[JonasToth]

• [Misc] emphasize goto in warning message

[xazax.hun]

A high level comment: while it is very easy to get all the gotos using grep, it is not so easy to get all the labels. So for this check to be complete, I think it would be useful to also find labels (possibly having a configuration option for that).

[JonasToth]

• [Misc] reformat

[JonasToth]

In D41815#969626, @xazax.hun wrote:

A high level comment: while it is very easy to get all the gotos using grep, it is not so easy to get all the labels. So for this check to be complete, I think it would be useful to also find labels (possibly having a configuration option for that).

Agreed. I will add warnings for jump labels too. Do you think a note where a goto jumps to would be helpful too?

[aaron.ballman]

In D41815#969673, @JonasToth wrote:

In D41815#969626, @xazax.hun wrote:

A high level comment: while it is very easy to get all the gotos using grep, it is not so easy to get all the labels. So for this check to be complete, I think it would be useful to also find labels (possibly having a configuration option for that).

Agreed. I will add warnings for jump labels too. Do you think a note where a goto jumps to would be helpful too?

Rather than add a warning for the labels, I would just add a note for the label when diagnosing the goto (since the goto has a single target).

clang-tidy/cppcoreguidelines/AvoidGotoCheck.cpp

23

Are you planning to add the exception listed in the C++ Core Guideline? It makes an explicit exception allowing you to jump forward out of a loop construct.

23

What should this check do with indirect goto statements (it's a GCC extension we support where you can jump to an expression)?

Regardless, there should be a test for indirect gotos and jump forward out of loop constructs.

28–29

I don't think this diagnostic really helps the user all that much. It doesn't say what's harmful about the goto, nor what high level programming construct to use to make it not harmful.

docs/clang-tidy/checks/cppcoreguidelines-avoid-goto.rst

7–8

This doesn't really help the user understand what's bad about goto or why it should be diagnosed. You should expound a bit here.

[JonasToth]

Rather than add a warning for the labels, I would just add a note for the label when diagnosing the goto (since the goto has a single target).

That might lead to existing labels without any gotos for them, does it? Maybe the check could also diagnose labels without corresponding gotos, or does the frontend already have something like this?

[aaron.ballman]

In D41815#969708, @JonasToth wrote:

Rather than add a warning for the labels, I would just add a note for the label when diagnosing the goto (since the goto has a single target).

That might lead to existing labels without any gotos for them, does it? Maybe the check could also diagnose labels without corresponding gotos, or does the frontend already have something like this?

-Wunused-label already covers this scenario.

[JonasToth]

clang-tidy/cppcoreguidelines/AvoidGotoCheck.cpp

23

Are you planning to add the exception listed in the C++ Core Guideline? It makes an explicit exception allowing you to jump forward out of a loop construct.

I do plan for this. Because I dont have any experience with gotos I wanted to do it in small steps.

What should this check do with indirect goto statements (it's a GCC extension we support where you can jump to an expression)?

Iam not aware of these :)

28–29

I dont like the diagnostic too. But i dont know how to give a sensefull short message.

Here Andrei Alexandrescu introduced some high level rules, maybe i the Rule of Minimum Power could be a starting point?
https://github.com/isocpp/CppCoreGuidelines/issues/19

Good example for Rule of Minimum Power: goto is the most powerful looping construct (it can do everything while does, and a lot more such as jumping in the middle of a loop etc.) and the most unrecommended.

[aaron.ballman]

clang-tidy/cppcoreguidelines/AvoidGotoCheck.cpp

23

What should this check do with indirect goto statements (it's a GCC extension we support where you can jump to an expression)?

Iam not aware of these :)

https://gcc.gnu.org/onlinedocs/gcc/Labels-as-Values.html
(and a good reference on why these are interesting: https://eli.thegreenplace.net/2012/07/12/computed-goto-for-efficient-dispatch-tables)

28–29

I think part of the issue here is that goto isn't harmful in all circumstances, but this check is going to tell users to remove the goto regardless of whether it's dangerous or not. That kind of broad prohibition suggests the diagnostic wording should be more along the lines of "avoid using 'goto' for flow control" or something along those lines. When you add the exception case(s) to the rule, you could reword to "this use of 'goto' for flow control is prohibited" (or similar).

[Eugene.Zelenko]

docs/ReleaseNotes.rst

63

I think will be good idea to reformulate this statement and its copy in documentation. diagnosed with this check is tautological for any check.

[JonasToth]

clang-tidy/cppcoreguidelines/AvoidGotoCheck.cpp

23

I would think that this is a special feature that will only be used if you know what you are doing. So it should be allowed with configuration. I am not sure about the default though. For now it is ignored.

HICPP has a rule on gotos as well, which states that only forward jumps are allowed.

I think that these different approaches to goto should land here sometime as different configurations.

[JonasToth]

I enhanced the check to do more:

• check that jumps will only be forward. AFAIK that is required in all sensefull usecases of goto, is it?
• additionally check for gotos in nested loops. These are not diagnosed if the jump is forward implementing the exception in the core guidelines.

With these modifications the check can be used to enforce the rule in the
CoreGuidelines and the goto part of 6.3.1 Ensure that the label(s) for a jump statement or a switch condition appear later, in the same or an enclosing block
for the HICPP module.

Some test cases for all combinations are missing, i can add those once you
agree that the functionality change is indeed ok.

[lebedev.ri]

In D41815#973260, @JonasToth wrote:

• check that jumps will only be forward. AFAIK that is required in all sensefull usecases of goto, is it?

You could implement loops/recursion with goto, something like:

const int end = 10;
int i = 0;
assert(i < end);

begin:
<do stuff>
i++
if(i < end)
  goto begin;

// end

But it really should be done with normal for(), or while(), so i think it would make sense to diagnose those.

[aaron.ballman]

In D41815#973260, @JonasToth wrote:

I enhanced the check to do more:

• check that jumps will only be forward. AFAIK that is required in all sensefull usecases of goto, is it?
• additionally check for gotos in nested loops. These are not diagnosed if the jump is forward implementing the exception in the core guidelines.

With these modifications the check can be used to enforce the rule in the
CoreGuidelines and the goto part of 6.3.1 Ensure that the label(s) for a jump statement or a switch condition appear later, in the same or an enclosing block
for the HICPP module.

Nice!

Some test cases for all combinations are missing, i can add those once you
agree that the functionality change is indeed ok.

I think this is the correct direction for the check.

clang-tidy/cppcoreguidelines/AvoidGotoCheck.cpp

22

Can remove the spurious newline.

23

I would think that this is a special feature that will only be used if you know what you are doing. So it should be allowed with configuration. I am not sure about the default though. For now it is ignored.

Ignoring it for now seems reasonable to me. You should add a TODO comment for it so we don't lose track of it, though.

HICPP has a rule on gotos as well, which states that only forward jumps are allowed.

That's essentially the same exception as the C++ Core Guidelines, which is nice.

I think that these different approaches to goto should land here sometime as different configurations.

Agreed, if needed.

27

s/then/than

42–54

Is there a reason to have two separate diagnostics? It seems like these both would be covered by "this use of 'goto' for flow control is prohibited".

[lebedev.ri]

clang-tidy/cppcoreguidelines/AvoidGotoCheck.cpp

21

It would be nice to have it in standard ASTMatchers, i believe it will be useful for else-after-return check.
Though the ASTMatchers are stuck due to the doc-dumping script being 'broken' (see D41455)

[JonasToth]

In D41815#973265, @lebedev.ri wrote:

In D41815#973260, @JonasToth wrote:

• check that jumps will only be forward. AFAIK that is required in all sensefull usecases of goto, is it?

You could implement loops/recursion with goto, something like:

const int end = 10;
int i = 0;
assert(i < end);

begin:
<do stuff>
i++
if(i < end)
  goto begin;

// end

But it really should be done with normal for(), or while(), so i think it would make sense to diagnose those.

That check is specifically targeting these code constellations to be bad practice. As you said, using the looping constructs is the way to go :)

[JonasToth]

clang-tidy/cppcoreguidelines/AvoidGotoCheck.cpp

21

Yes. The GNU extension goto does not have ASTMatcher yet, so i will pack these together in a review. What do you think how long the ASTMatcher issue will be there? Maybe it could be done after that check lands?

42–54

Yes, the new wording better. The note about the backward jump could be added in the label defined here note. I think distignuishing between backward jumps and forward jumps is still a good thing.

The forward jumps could come from a C code part where forward jumps are done for resource cleaning. So having a strong prohibited and a suggesting avoid diagnostic makes sense to me.

[lebedev.ri]

clang-tidy/cppcoreguidelines/AvoidGotoCheck.cpp

21

Maybe it could be done after that check lands?

Yes, absolutely. I did not meant that as a blocker here.

[JonasToth]

clang-tidy/cppcoreguidelines/AvoidGotoCheck.cpp

21

On my todo list.

[JonasToth]

• address review comments
• add better documentation with code examples

[JonasToth]

docs/ReleaseNotes.rst

63

Reformulated, is it ok now?

docs/clang-tidy/checks/cppcoreguidelines-avoid-goto.rst

7–8

Is it better now?

[JonasToth]

• simplified the code and merged diagnostics

[Eugene.Zelenko]

docs/clang-tidy/checks/cppcoreguidelines-avoid-goto.rst

7–8

Much better now! Thank you for fix!

[lebedev.ri]

clang-tidy/cppcoreguidelines/AvoidGotoCheck.cpp

22

Hm, on a second thought, i think this will have false-positive if the label and the goto are on the same line, like

goto label; ; label: ;

I wonder we could easily compare accounting for the position in the line, or it is not worth the extra complexity.

[JonasToth]

• add edgecase test from roman

clang-tidy/cppcoreguidelines/AvoidGotoCheck.cpp

22

Iam not sure what you mean. Is the concern that the goto does not actually skip something?
If yes it is still worth it, because its not necessary to have the goto then.

The < on the locations should always be sensefull because AFAIK its at byte level (or something similar).

Your example is diagnosed correctly.

[lebedev.ri]

clang-tidy/cppcoreguidelines/AvoidGotoCheck.cpp

22

The < on the locations should always be sensefull because AFAIK its at byte level (or something similar).

Ah, great then. I had some recollections of having some issues with that before, but it makes sense that it would just work.

[aaron.ballman]

clang-tidy/cppcoreguidelines/AvoidGotoCheck.cpp

21

I'm not certain adding this to the AST matchers is critical. For instance, we may want to, instead, consider adding relational operators for source locations and then expose a generic facility for getting source location information out of AST nodes.

27

separatly -> separately
a ASTMatcher -> an AST matcher

29–30

We don't usually put names into the source code and given the questions about adding that matcher, I'd say it's better to remove the promise that this will become a generic one.

44

I think that this check should be C++ only. C makes far more use of goto, and backwards jumps are not always bad there (they don't have to consider things like destructors or RAII like you do in C++).

Esp since this is a check for the C++ core guidelines and HICPP (both are C++ standards).

docs/ReleaseNotes.rst

74–75

I think you should also add the HICPP changes as well, given that this check also covers that rule.

[JonasToth]

clang-tidy/cppcoreguidelines/AvoidGotoCheck.cpp

22

I dont know the internals, i just assume because it works :)

[JonasToth]

• address review comments

clang-tidy/cppcoreguidelines/AvoidGotoCheck.cpp

44

Ok. I merged the matchers too.

docs/ReleaseNotes.rst

74–75

I think Only forward jumps in nested loops are accepted. covers it, but i reformulated it.

[JonasToth]

• [Fix] bug with language mode

[JonasToth]

• doc clarified that check is c++ only
• add missing tests for do and range-for, not all combinations done, but every loop construct is used as outer and inner loop

[aaron.ballman]

clang-tidy/cppcoreguidelines/AvoidGotoCheck.h

20–21

This comment is a bit out of date now that it no longer diagnoses all uses of goto.

[JonasToth]

• hicpp alias added
• update documentation

[JonasToth]

• remove spurious whitespace

[JonasToth]

• last nits i found

[aaron.ballman]

LGTM aside from a minor formatting nit.

clang-tidy/hicpp/HICPPTidyModule.cpp

57

Spurious formatting change -- feel free to commit separately (no review required) if you want to fix it.

[JonasToth]

• [Misc] remove spurious format

clang-tidy/cppcoreguidelines/AvoidGotoCheck.h

+//===--- AvoidGotoCheck.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_CPPCOREGUIDELINES_AVOIDGOTOCHECK_H
+#define LLVM_CLANG_TOOLS_EXTRA_CLANG_TIDY_CPPCOREGUIDELINES_AVOIDGOTOCHECK_H
+
+#include "../ClangTidy.h"
+
+namespace clang {
+namespace tidy {
+namespace cppcoreguidelines {
+
+/// The usage of ``goto`` for control flow is error prone and should be replaced
+/// with looping constructs. Only forward jumps in nested loops are accepted.
+//
+/// For the user-facing documentation see:
+/// http://clang.llvm.org/extra/clang-tidy/checks/cppcoreguidelines-avoid-goto.html
+class AvoidGotoCheck : public ClangTidyCheck {
+public:
+  AvoidGotoCheck(StringRef Name, ClangTidyContext *Context)
+      : ClangTidyCheck(Name, Context) {}
+  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_AVOIDGOTOCHECK_H

clang-tidy/cppcoreguidelines/AvoidGotoCheck.cpp

+//===--- AvoidGotoCheck.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 "AvoidGotoCheck.h"
+#include "clang/AST/ASTContext.h"
+#include "clang/ASTMatchers/ASTMatchFinder.h"
+
+using namespace clang::ast_matchers;
+
+namespace clang {
+namespace tidy {
+namespace cppcoreguidelines {
+
+AST_MATCHER(GotoStmt, isForwardJumping) {
+  return Node.getLocStart() < Node.getLabel()->getLocStart();
+}
+
+void AvoidGotoCheck::registerMatchers(MatchFinder *Finder) {
+  if (!getLangOpts().CPlusPlus)
+    return;
+
+  // TODO: This check does not recognize `IndirectGotoStmt` which is a
+  // GNU extension. These must be matched separately and an AST matcher
+  // is currently missing for them.
+
+  // Check if the 'goto' is used for control flow other than jumping
+  // out of a nested loop.
+  auto Loop = stmt(anyOf(forStmt(), cxxForRangeStmt(), whileStmt(), doStmt()));
+  auto NestedLoop =
+      stmt(anyOf(forStmt(hasAncestor(Loop)), cxxForRangeStmt(hasAncestor(Loop)),
+                 whileStmt(hasAncestor(Loop)), doStmt(hasAncestor(Loop))));
+
+  Finder->addMatcher(gotoStmt(anyOf(unless(hasAncestor(NestedLoop)),
+                                    unless(isForwardJumping())))
+                         .bind("goto"),
+                     this);
+}
+
+void AvoidGotoCheck::check(const MatchFinder::MatchResult &Result) {
+  const auto *Goto = Result.Nodes.getNodeAs<GotoStmt>("goto");
+
+  diag(Goto->getGotoLoc(), "avoid using 'goto' for flow control")
+      << Goto->getSourceRange();
+  diag(Goto->getLabel()->getLocStart(), "label defined here",
+       DiagnosticIDs::Note);
+}
+} // namespace cppcoreguidelines
+} // namespace tidy
+} // namespace clang

clang-tidy/cppcoreguidelines/CMakeLists.txt

 set(LLVM_LINK_COMPONENTS support)
 
 add_clang_library(clangTidyCppCoreGuidelinesModule
+  AvoidGotoCheck.cpp
   CppCoreGuidelinesTidyModule.cpp
   InterfacesGlobalInitCheck.cpp
   NoMallocCheck.cpp
   OwningMemoryCheck.cpp
   ProBoundsArrayToPointerDecayCheck.cpp
   ProBoundsConstantArrayIndexCheck.cpp
   ProBoundsPointerArithmeticCheck.cpp
   ProTypeConstCastCheck.cpp

clang-tidy/cppcoreguidelines/CppCoreGuidelinesTidyModule.cpp

 //===--- CppCoreGuidelinesModule.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 "../ClangTidy.h"
 #include "../ClangTidyModule.h"
 #include "../ClangTidyModuleRegistry.h"
 #include "../misc/UnconventionalAssignOperatorCheck.h"
+#include "AvoidGotoCheck.h"
 #include "InterfacesGlobalInitCheck.h"
 #include "NoMallocCheck.h"
 #include "OwningMemoryCheck.h"
 #include "ProBoundsArrayToPointerDecayCheck.h"
 #include "ProBoundsConstantArrayIndexCheck.h"
 #include "ProBoundsPointerArithmeticCheck.h"
 #include "ProTypeConstCastCheck.h"
 #include "ProTypeCstyleCastCheck.h"
 #include "ProTypeMemberInitCheck.h"
 #include "ProTypeReinterpretCastCheck.h"
 #include "ProTypeStaticCastDowncastCheck.h"
 #include "ProTypeUnionAccessCheck.h"
 #include "ProTypeVarargCheck.h"
 #include "SlicingCheck.h"
 #include "SpecialMemberFunctionsCheck.h"
 
 namespace clang {
 namespace tidy {
 namespace cppcoreguidelines {
 
 /// A module containing checks of the C++ Core Guidelines
 class CppCoreGuidelinesModule : public ClangTidyModule {
 public:
   void addCheckFactories(ClangTidyCheckFactories &CheckFactories) override {
+    CheckFactories.registerCheck<AvoidGotoCheck>(
+        "cppcoreguidelines-avoid-goto");
     CheckFactories.registerCheck<InterfacesGlobalInitCheck>(
         "cppcoreguidelines-interfaces-global-init");
     CheckFactories.registerCheck<NoMallocCheck>("cppcoreguidelines-no-malloc");
     CheckFactories.registerCheck<OwningMemoryCheck>(
         "cppcoreguidelines-owning-memory");
     CheckFactories.registerCheck<ProBoundsArrayToPointerDecayCheck>(
         "cppcoreguidelines-pro-bounds-array-to-pointer-decay");
     CheckFactories.registerCheck<ProBoundsConstantArrayIndexCheck>(

clang-tidy/hicpp/HICPPTidyModule.cpp

 //===------- HICPPTidyModule.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 "../ClangTidy.h"
 #include "../ClangTidyModule.h"
 #include "../ClangTidyModuleRegistry.h"
 #include "../bugprone/UseAfterMoveCheck.h"
+#include "../cppcoreguidelines/AvoidGotoCheck.h"
 #include "../cppcoreguidelines/NoMallocCheck.h"
 #include "../cppcoreguidelines/ProBoundsArrayToPointerDecayCheck.h"
 #include "../cppcoreguidelines/ProTypeMemberInitCheck.h"
 #include "../cppcoreguidelines/ProTypeVarargCheck.h"
 #include "../cppcoreguidelines/SpecialMemberFunctionsCheck.h"
 #include "../google/DefaultArgumentsCheck.h"
 #include "../google/ExplicitConstructorCheck.h"
 #include "../misc/NewDeleteOverloadsCheck.h"

 
 namespace clang {
 namespace tidy {
 namespace hicpp {
 
 class HICPPModule : public ClangTidyModule {
 public:
   void addCheckFactories(ClangTidyCheckFactories &CheckFactories) override {
+    CheckFactories.registerCheck<cppcoreguidelines::AvoidGotoCheck>(
+        "hicpp-avoid-goto");
     CheckFactories.registerCheck<readability::BracesAroundStatementsCheck>(
         "hicpp-braces-around-statements");
     CheckFactories.registerCheck<modernize::DeprecatedHeadersCheck>(
         "hicpp-deprecated-headers");
     CheckFactories.registerCheck<ExceptionBaseclassCheck>(
         "hicpp-exception-baseclass");
     CheckFactories.registerCheck<SignedBitwiseCheck>("hicpp-signed-bitwise");
     CheckFactories.registerCheck<google::ExplicitConstructorCheck>(
         "hicpp-explicit-conversions");
     CheckFactories.registerCheck<readability::FunctionSizeCheck>(
         "hicpp-function-size");
     CheckFactories.registerCheck<readability::IdentifierNamingCheck>(
         "hicpp-named-parameter");
     CheckFactories.registerCheck<bugprone::UseAfterMoveCheck>(
         "hicpp-invalid-access-moved");

docs/ReleaseNotes.rst

 Improvements to clang-rename
 ----------------------------
 
 The improvements are...
 
 Improvements to clang-tidy
 --------------------------
 
+- New `cppcoreguidelines-avoid-goto
+  <http://clang.llvm.org/extra/clang-tidy/checks/cppcoreguidelines-avoid-goto.html>`_ check
+
+  The usage of ``goto`` for control flow is error prone and should be replaced
+  with looping constructs. Every backward jump is rejected. Forward jumps are
+  only allowed in nested loops.
+
 - New `fuchsia-statically-constructed-objects
   <http://clang.llvm.org/extra/clang-tidy/checks/fuchsia-statically-constructed-objects.html>`_ check
 
   Warns if global, non-trivial objects with static storage are constructed, unless the 
   object is statically initialized with a ``constexpr`` constructor or has no 
   explicit constructor.
 
+- New alias `hicpp-avoid-goto
+  <http://clang.llvm.org/extra/clang-tidy/checks/hicpp-avoid-goto.html>`_ to 
+  `cppcoreguidelines-avoid-goto <http://clang.llvm.org/extra/clang-tidy/checks/cppcoreguidelines-avoid-goto.html>`_
+  added.
+
 Improvements to include-fixer
 -----------------------------
 
 The improvements are...
 
 Improvements to modularize
 --------------------------
 
 The improvements are...

docs/clang-tidy/checks/cppcoreguidelines-avoid-goto.rst

+.. title:: clang-tidy - cppcoreguidelines-avoid-goto
+
+cppcoreguidelines-avoid-goto
+============================
+
+The usage of ``goto`` for control flow is error prone and should be replaced
+with looping constructs. Only forward jumps in nested loops are accepted.
+
+This check implements `ES.76 <https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md#es76-avoid-goto>`_ 
+from the CppCoreGuidelines and 
+`6.3.1 from High Integrity C++ <http://www.codingstandard.com/rule/6-3-1-ensure-that-the-labels-for-a-jump-statement-or-a-switch-condition-appear-later-in-the-same-or-an-enclosing-block/>`_.
+
+For more information on why to avoid programming 
+with ``goto`` you can read the famous paper `A Case against the GO TO Statement. <https://www.cs.utexas.edu/users/EWD/ewd02xx/EWD215.PDF>`_.
+
+The check diagnoses ``goto`` for backward jumps in every language mode. These
+should be replaced with `C/C++` looping constructs.
+
+.. code-block:: c++
+
+  // Bad, handwritten for loop.
+  int i = 0;
+  // Jump label for the loop
+  loop_start:
+  do_some_operation();
+
+  if (i < 100) {
+    ++i;
+    goto loop_start;
+  }
+
+  // Better
+  for(int i = 0; i < 100; ++i)
+    do_some_operation();
+
+Modern C++ needs ``goto`` only to jump out of nested loops.
+
+.. code-block:: c++
+
+  for(int i = 0; i < 100; ++i) {
+    for(int j = 0; j < 100; ++j) {
+      if (i * j > 500)
+        goto early_exit;
+    }
+  }
+
+  early_exit:
+  some_operation();
+
+All other uses of ``goto`` are diagnosed in `C++`.

docs/clang-tidy/checks/hicpp-avoid-goto.rst

+.. title:: clang-tidy - hicpp-avoid-goto
+
+hicpp-avoid-goto
+================
+
+The `hicpp-avoid-goto` check is an alias to 
+`cppcoreguidelines-avoid-goto <cppcoreguidelines-avoid-goto.html>`_.
+Rule `6.3.1 High Integrity C++ <http://www.codingstandard.com/rule/6-3-1-ensure-that-the-labels-for-a-jump-statement-or-a-switch-condition-appear-later-in-the-same-or-an-enclosing-block/>`_
+requires that ``goto`` only skips parts of a block and is not used for other 
+reasons.
+
+Both coding guidelines implement the same exception to the usage of ``goto``.

docs/clang-tidy/checks/list.rst

.. toctree::
    cert-err58-cpp
    cert-err60-cpp
    cert-err61-cpp (redirects to misc-throw-by-value-catch-by-reference) <cert-err61-cpp>
    cert-fio38-c (redirects to misc-non-copyable-objects) <cert-fio38-c>
    cert-flp30-c
    cert-msc30-c (redirects to cert-msc50-cpp) <cert-msc30-c>
    cert-msc50-cpp
    cert-oop11-cpp (redirects to performance-move-constructor-init) <cert-oop11-cpp>
+   cppcoreguidelines-avoid-goto
    cppcoreguidelines-c-copy-assignment-signature (redirects to misc-unconventional-assign-operator) <cppcoreguidelines-c-copy-assignment-signature>
    cppcoreguidelines-interfaces-global-init
    cppcoreguidelines-no-malloc
    cppcoreguidelines-owning-memory
    cppcoreguidelines-pro-bounds-array-to-pointer-decay
    cppcoreguidelines-pro-bounds-constant-array-index
    cppcoreguidelines-pro-bounds-pointer-arithmetic
    cppcoreguidelines-pro-type-const-cast
.. toctree::
    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
    google-runtime-operator
    google-runtime-references
+   hicpp-avoid-goto (redirects to cppcoreguidelines-avoid-goto) <hicpp-avoid-goto>
    hicpp-braces-around-statements (redirects to readability-braces-around-statements) <hicpp-braces-around-statements>
    hicpp-deprecated-headers (redirects to modernize-deprecated-headers) <hicpp-deprecated-headers>
    hicpp-exception-baseclass
    hicpp-explicit-conversions (redirects to google-explicit-constructor) <hicpp-explicit-conversions>
    hicpp-function-size (redirects to readability-function-size) <hicpp-function-size>
    hicpp-invalid-access-moved (redirects to bugprone-use-after-move) <hicpp-invalid-access-moved>
    hicpp-member-init (redirects to cppcoreguidelines-pro-type-member-init) <hicpp-member-init>
    hicpp-move-const-arg (redirects to performance-move-const-arg) <hicpp-move-const-arg>

test/clang-tidy/cppcoreguidelines-avoid-goto.cpp

+// RUN: %check_clang_tidy %s cppcoreguidelines-avoid-goto %t
+
+void noop() {}
+
+int main() {
+  noop();
+  goto jump_to_me;
+  // CHECK-MESSAGES: [[@LINE-1]]:3: warning: avoid using 'goto' for flow control
+  // CHECK-MESSAGES: [[@LINE+3]]:1: note: label defined here
+  noop();
+
+jump_to_me:;
+
+jump_backwards:;
+  noop();
+  goto jump_backwards;
+  // CHECK-MESSAGES: [[@LINE-1]]:3: warning: avoid using 'goto' for flow control
+  // CHECK-MESSAGES: [[@LINE-4]]:1: note: label defined here
+
+  goto jump_in_line;
+  ;
+jump_in_line:;
+  // CHECK-MESSAGES: [[@LINE-3]]:3: warning: avoid using 'goto' for flow control
+  // CHECK-MESSAGES: [[@LINE-2]]:1: note: label defined here
+
+  // Test the GNU extension https://gcc.gnu.org/onlinedocs/gcc/Labels-as-Values.html
+some_label:;
+  void *dynamic_label = &&some_label;
+
+  // FIXME: `IndirectGotoStmt` is not detected.
+  goto *dynamic_label;
+}
+
+void forward_jump_out_nested_loop() {
+  int array[] = {1, 2, 3, 4, 5};
+  for (int i = 0; i < 10; ++i) {
+    noop();
+    for (int j = 0; j < 10; ++j) {
+      noop();
+      if (i + j > 10)
+        goto early_exit1;
+    }
+    noop();
+  }
+
+  for (int i = 0; i < 10; ++i) {
+    noop();
+    while (true) {
+      noop();
+      if (i > 5)
+        goto early_exit1;
+    }
+    noop();
+  }
+
+  for (auto value : array) {
+    noop();
+    for (auto number : array) {
+      noop();
+      if (number == 5)
+        goto early_exit1;
+    }
+  }
+
+  do {
+    noop();
+    do {
+      noop();
+      goto early_exit1;
+    } while (true);
+  } while (true);
+
+  do {
+    for (auto number : array) {
+      noop();
+      if (number == 2)
+        goto early_exit1;
+    }
+  } while (true);
+
+  // Jumping further results in error, because the variable declaration would
+  // be skipped.
+early_exit1:;
+
+  int i = 0;
+  while (true) {
+    noop();
+    while (true) {
+      noop();
+      if (i > 5)
+        goto early_exit2;
+      i++;
+    }
+    noop();
+  }
+
+  while (true) {
+    noop();
+    for (int j = 0; j < 10; ++j) {
+      noop();
+      if (j > 5)
+        goto early_exit2;
+    }
+    noop();
+  }
+
+  while (true) {
+    noop();
+    for (auto number : array) {
+      if (number == 1)
+        goto early_exit2;
+      noop();
+    }
+  }
+
+  while (true) {
+    noop();
+    do {
+      noop();
+      goto early_exit2;
+    } while (true);
+  }
+early_exit2:;
+}
+
+void jump_out_backwards() {
+
+before_the_loop:
+  noop();
+
+  for (int i = 0; i < 10; ++i) {
+    for (int j = 0; j < 10; ++j) {
+      if (i * j > 80)
+        goto before_the_loop;
+      // CHECK-MESSAGES: [[@LINE-1]]:9: warning: avoid using 'goto' for flow control
+      // CHECK-MESSAGES: [[@LINE-8]]:1: note: label defined here
+    }
+  }
+}