View Javadoc
1   ///////////////////////////////////////////////////////////////////////////////////////////////
2   // checkstyle: Checks Java source code and other text files for adherence to a set of rules.
3   // Copyright (C) 2001-2024 the original author or authors.
4   //
5   // This library is free software; you can redistribute it and/or
6   // modify it under the terms of the GNU Lesser General Public
7   // License as published by the Free Software Foundation; either
8   // version 2.1 of the License, or (at your option) any later version.
9   //
10  // This library is distributed in the hope that it will be useful,
11  // but WITHOUT ANY WARRANTY; without even the implied warranty of
12  // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
13  // Lesser General Public License for more details.
14  //
15  // You should have received a copy of the GNU Lesser General Public
16  // License along with this library; if not, write to the Free Software
17  // Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
18  ///////////////////////////////////////////////////////////////////////////////////////////////
19  
20  package com.puppycrawl.tools.checkstyle.checks.metrics;
21  
22  import java.math.BigInteger;
23  import java.util.ArrayDeque;
24  import java.util.Deque;
25  
26  import com.puppycrawl.tools.checkstyle.FileStatefulCheck;
27  import com.puppycrawl.tools.checkstyle.api.AbstractCheck;
28  import com.puppycrawl.tools.checkstyle.api.DetailAST;
29  import com.puppycrawl.tools.checkstyle.api.TokenTypes;
30  
31  /**
32   * <p>
33   * Checks cyclomatic complexity against a specified limit. It is a measure of
34   * the minimum number of possible paths through the source and therefore the
35   * number of required tests, it is not about quality of code! It is only
36   * applied to methods, c-tors,
37   * <a href="https://docs.oracle.com/javase/tutorial/java/javaOO/initial.html">
38   * static initializers and instance initializers</a>.
39   * </p>
40   * <p>
41   * The complexity is equal to the number of decision points {@code + 1}.
42   * Decision points: {@code if}, {@code while}, {@code do}, {@code for},
43   * {@code ?:}, {@code catch}, {@code switch}, {@code case} statements and
44   * operators {@code &amp;&amp;} and {@code ||} in the body of target.
45   * </p>
46   * <p>
47   * By pure theory level 1-4 is considered easy to test, 5-7 OK, 8-10 consider
48   * re-factoring to ease testing, and 11+ re-factor now as testing will be painful.
49   * </p>
50   * <p>
51   * When it comes to code quality measurement by this metric level 10 is very
52   * good level as a ultimate target (that is hard to archive). Do not be ashamed
53   * to have complexity level 15 or even higher, but keep it below 20 to catch
54   * really bad-designed code automatically.
55   * </p>
56   * <p>
57   * Please use Suppression to avoid violations on cases that could not be split
58   * in few methods without damaging readability of code or encapsulation.
59   * </p>
60   * <ul>
61   * <li>
62   * Property {@code max} - Specify the maximum threshold allowed.
63   * Type is {@code int}.
64   * Default value is {@code 10}.
65   * </li>
66   * <li>
67   * Property {@code switchBlockAsSingleDecisionPoint} - Control whether to treat
68   * the whole switch block as a single decision point.
69   * Type is {@code boolean}.
70   * Default value is {@code false}.
71   * </li>
72   * <li>
73   * Property {@code tokens} - tokens to check
74   * Type is {@code java.lang.String[]}.
75   * Validation type is {@code tokenSet}.
76   * Default value is:
77   * <a href="https://checkstyle.org/apidocs/com/puppycrawl/tools/checkstyle/api/TokenTypes.html#LITERAL_WHILE">
78   * LITERAL_WHILE</a>,
79   * <a href="https://checkstyle.org/apidocs/com/puppycrawl/tools/checkstyle/api/TokenTypes.html#LITERAL_DO">
80   * LITERAL_DO</a>,
81   * <a href="https://checkstyle.org/apidocs/com/puppycrawl/tools/checkstyle/api/TokenTypes.html#LITERAL_FOR">
82   * LITERAL_FOR</a>,
83   * <a href="https://checkstyle.org/apidocs/com/puppycrawl/tools/checkstyle/api/TokenTypes.html#LITERAL_IF">
84   * LITERAL_IF</a>,
85   * <a href="https://checkstyle.org/apidocs/com/puppycrawl/tools/checkstyle/api/TokenTypes.html#LITERAL_SWITCH">
86   * LITERAL_SWITCH</a>,
87   * <a href="https://checkstyle.org/apidocs/com/puppycrawl/tools/checkstyle/api/TokenTypes.html#LITERAL_CASE">
88   * LITERAL_CASE</a>,
89   * <a href="https://checkstyle.org/apidocs/com/puppycrawl/tools/checkstyle/api/TokenTypes.html#LITERAL_CATCH">
90   * LITERAL_CATCH</a>,
91   * <a href="https://checkstyle.org/apidocs/com/puppycrawl/tools/checkstyle/api/TokenTypes.html#QUESTION">
92   * QUESTION</a>,
93   * <a href="https://checkstyle.org/apidocs/com/puppycrawl/tools/checkstyle/api/TokenTypes.html#LAND">
94   * LAND</a>,
95   * <a href="https://checkstyle.org/apidocs/com/puppycrawl/tools/checkstyle/api/TokenTypes.html#LOR">
96   * LOR</a>.
97   * </li>
98   * </ul>
99   * <p>
100  * Parent is {@code com.puppycrawl.tools.checkstyle.TreeWalker}
101  * </p>
102  * <p>
103  * Violation Message Keys:
104  * </p>
105  * <ul>
106  * <li>
107  * {@code cyclomaticComplexity}
108  * </li>
109  * </ul>
110  *
111  * @since 3.2
112  */
113 @FileStatefulCheck
114 public class CyclomaticComplexityCheck
115     extends AbstractCheck {
116 
117     /**
118      * A key is pointing to the warning message text in "messages.properties"
119      * file.
120      */
121     public static final String MSG_KEY = "cyclomaticComplexity";
122 
123     /** The initial current value. */
124     private static final BigInteger INITIAL_VALUE = BigInteger.ONE;
125 
126     /** Default allowed complexity. */
127     private static final int DEFAULT_COMPLEXITY_VALUE = 10;
128 
129     /** Stack of values - all but the current value. */
130     private final Deque<BigInteger> valueStack = new ArrayDeque<>();
131 
132     /** Control whether to treat the whole switch block as a single decision point. */
133     private boolean switchBlockAsSingleDecisionPoint;
134 
135     /** The current value. */
136     private BigInteger currentValue = INITIAL_VALUE;
137 
138     /** Specify the maximum threshold allowed. */
139     private int max = DEFAULT_COMPLEXITY_VALUE;
140 
141     /**
142      * Setter to control whether to treat the whole switch block as a single decision point.
143      *
144      * @param switchBlockAsSingleDecisionPoint whether to treat the whole switch
145      *                                          block as a single decision point.
146      * @since 6.11
147      */
148     public void setSwitchBlockAsSingleDecisionPoint(boolean switchBlockAsSingleDecisionPoint) {
149         this.switchBlockAsSingleDecisionPoint = switchBlockAsSingleDecisionPoint;
150     }
151 
152     /**
153      * Setter to specify the maximum threshold allowed.
154      *
155      * @param max the maximum threshold
156      * @since 3.2
157      */
158     public final void setMax(int max) {
159         this.max = max;
160     }
161 
162     @Override
163     public int[] getDefaultTokens() {
164         return new int[] {
165             TokenTypes.CTOR_DEF,
166             TokenTypes.METHOD_DEF,
167             TokenTypes.INSTANCE_INIT,
168             TokenTypes.STATIC_INIT,
169             TokenTypes.LITERAL_WHILE,
170             TokenTypes.LITERAL_DO,
171             TokenTypes.LITERAL_FOR,
172             TokenTypes.LITERAL_IF,
173             TokenTypes.LITERAL_SWITCH,
174             TokenTypes.LITERAL_CASE,
175             TokenTypes.LITERAL_CATCH,
176             TokenTypes.QUESTION,
177             TokenTypes.LAND,
178             TokenTypes.LOR,
179             TokenTypes.COMPACT_CTOR_DEF,
180         };
181     }
182 
183     @Override
184     public int[] getAcceptableTokens() {
185         return new int[] {
186             TokenTypes.CTOR_DEF,
187             TokenTypes.METHOD_DEF,
188             TokenTypes.INSTANCE_INIT,
189             TokenTypes.STATIC_INIT,
190             TokenTypes.LITERAL_WHILE,
191             TokenTypes.LITERAL_DO,
192             TokenTypes.LITERAL_FOR,
193             TokenTypes.LITERAL_IF,
194             TokenTypes.LITERAL_SWITCH,
195             TokenTypes.LITERAL_CASE,
196             TokenTypes.LITERAL_CATCH,
197             TokenTypes.QUESTION,
198             TokenTypes.LAND,
199             TokenTypes.LOR,
200             TokenTypes.COMPACT_CTOR_DEF,
201         };
202     }
203 
204     @Override
205     public final int[] getRequiredTokens() {
206         return new int[] {
207             TokenTypes.CTOR_DEF,
208             TokenTypes.METHOD_DEF,
209             TokenTypes.INSTANCE_INIT,
210             TokenTypes.STATIC_INIT,
211             TokenTypes.COMPACT_CTOR_DEF,
212         };
213     }
214 
215     @Override
216     public void visitToken(DetailAST ast) {
217         switch (ast.getType()) {
218             case TokenTypes.CTOR_DEF:
219             case TokenTypes.METHOD_DEF:
220             case TokenTypes.INSTANCE_INIT:
221             case TokenTypes.STATIC_INIT:
222             case TokenTypes.COMPACT_CTOR_DEF:
223                 visitMethodDef();
224                 break;
225             default:
226                 visitTokenHook(ast);
227         }
228     }
229 
230     @Override
231     public void leaveToken(DetailAST ast) {
232         switch (ast.getType()) {
233             case TokenTypes.CTOR_DEF:
234             case TokenTypes.METHOD_DEF:
235             case TokenTypes.INSTANCE_INIT:
236             case TokenTypes.STATIC_INIT:
237             case TokenTypes.COMPACT_CTOR_DEF:
238                 leaveMethodDef(ast);
239                 break;
240             default:
241                 break;
242         }
243     }
244 
245     /**
246      * Hook called when visiting a token. Will not be called the method
247      * definition tokens.
248      *
249      * @param ast the token being visited
250      */
251     private void visitTokenHook(DetailAST ast) {
252         if (switchBlockAsSingleDecisionPoint) {
253             if (ast.getType() != TokenTypes.LITERAL_CASE) {
254                 incrementCurrentValue(BigInteger.ONE);
255             }
256         }
257         else if (ast.getType() != TokenTypes.LITERAL_SWITCH) {
258             incrementCurrentValue(BigInteger.ONE);
259         }
260     }
261 
262     /**
263      * Process the end of a method definition.
264      *
265      * @param ast the token representing the method definition
266      */
267     private void leaveMethodDef(DetailAST ast) {
268         final BigInteger bigIntegerMax = BigInteger.valueOf(max);
269         if (currentValue.compareTo(bigIntegerMax) > 0) {
270             log(ast, MSG_KEY, currentValue, bigIntegerMax);
271         }
272         popValue();
273     }
274 
275     /**
276      * Increments the current value by a specified amount.
277      *
278      * @param amount the amount to increment by
279      */
280     private void incrementCurrentValue(BigInteger amount) {
281         currentValue = currentValue.add(amount);
282     }
283 
284     /** Push the current value on the stack. */
285     private void pushValue() {
286         valueStack.push(currentValue);
287         currentValue = INITIAL_VALUE;
288     }
289 
290     /**
291      * Pops a value off the stack and makes it the current value.
292      */
293     private void popValue() {
294         currentValue = valueStack.pop();
295     }
296 
297     /** Process the start of the method definition. */
298     private void visitMethodDef() {
299         pushValue();
300     }
301 
302 }