001/////////////////////////////////////////////////////////////////////////////////////////////// 002// checkstyle: Checks Java source code and other text files for adherence to a set of rules. 003// Copyright (C) 2001-2024 the original author or authors. 004// 005// This library is free software; you can redistribute it and/or 006// modify it under the terms of the GNU Lesser General Public 007// License as published by the Free Software Foundation; either 008// version 2.1 of the License, or (at your option) any later version. 009// 010// This library is distributed in the hope that it will be useful, 011// but WITHOUT ANY WARRANTY; without even the implied warranty of 012// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 013// Lesser General Public License for more details. 014// 015// You should have received a copy of the GNU Lesser General Public 016// License along with this library; if not, write to the Free Software 017// Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA 018/////////////////////////////////////////////////////////////////////////////////////////////// 019 020package com.puppycrawl.tools.checkstyle.checks.metrics; 021 022import java.util.ArrayDeque; 023import java.util.Deque; 024 025import com.puppycrawl.tools.checkstyle.FileStatefulCheck; 026import com.puppycrawl.tools.checkstyle.api.AbstractCheck; 027import com.puppycrawl.tools.checkstyle.api.DetailAST; 028import com.puppycrawl.tools.checkstyle.api.TokenTypes; 029import com.puppycrawl.tools.checkstyle.utils.CheckUtil; 030 031/** 032 * <p> 033 * Restricts the number of boolean operators ({@code &&}, {@code ||}, 034 * {@code &}, {@code |} and {@code ^}) in an expression. 035 * </p> 036 * <p> 037 * Rationale: Too many conditions leads to code that is difficult to read 038 * and hence debug and maintain. 039 * </p> 040 * <p> 041 * Note that the operators {@code &} and {@code |} are not only integer bitwise 042 * operators, they are also the 043 * <a href="https://docs.oracle.com/javase/specs/jls/se11/html/jls-15.html#jls-15.22.2"> 044 * non-shortcut versions</a> of the boolean operators {@code &&} and {@code ||}. 045 * </p> 046 * <p> 047 * Note that {@code &}, {@code |} and {@code ^} are not checked if they are part 048 * of constructor or method call because they can be applied to non-boolean 049 * variables and Checkstyle does not know types of methods from different classes. 050 * </p> 051 * <ul> 052 * <li> 053 * Property {@code max} - Specify the maximum number of boolean operations 054 * allowed in one expression. 055 * Type is {@code int}. 056 * Default value is {@code 3}. 057 * </li> 058 * <li> 059 * Property {@code tokens} - tokens to check 060 * Type is {@code java.lang.String[]}. 061 * Validation type is {@code tokenSet}. 062 * Default value is: 063 * <a href="https://checkstyle.org/apidocs/com/puppycrawl/tools/checkstyle/api/TokenTypes.html#LAND"> 064 * LAND</a>, 065 * <a href="https://checkstyle.org/apidocs/com/puppycrawl/tools/checkstyle/api/TokenTypes.html#BAND"> 066 * BAND</a>, 067 * <a href="https://checkstyle.org/apidocs/com/puppycrawl/tools/checkstyle/api/TokenTypes.html#LOR"> 068 * LOR</a>, 069 * <a href="https://checkstyle.org/apidocs/com/puppycrawl/tools/checkstyle/api/TokenTypes.html#BOR"> 070 * BOR</a>, 071 * <a href="https://checkstyle.org/apidocs/com/puppycrawl/tools/checkstyle/api/TokenTypes.html#BXOR"> 072 * BXOR</a>. 073 * </li> 074 * </ul> 075 * <p> 076 * Parent is {@code com.puppycrawl.tools.checkstyle.TreeWalker} 077 * </p> 078 * <p> 079 * Violation Message Keys: 080 * </p> 081 * <ul> 082 * <li> 083 * {@code booleanExpressionComplexity} 084 * </li> 085 * </ul> 086 * 087 * @since 3.4 088 */ 089@FileStatefulCheck 090public final class BooleanExpressionComplexityCheck extends AbstractCheck { 091 092 /** 093 * A key is pointing to the warning message text in "messages.properties" 094 * file. 095 */ 096 public static final String MSG_KEY = "booleanExpressionComplexity"; 097 098 /** Default allowed complexity. */ 099 private static final int DEFAULT_MAX = 3; 100 101 /** Stack of contexts. */ 102 private final Deque<Context> contextStack = new ArrayDeque<>(); 103 /** Specify the maximum number of boolean operations allowed in one expression. */ 104 private int max; 105 /** Current context. */ 106 private Context context = new Context(false); 107 108 /** Creates new instance of the check. */ 109 public BooleanExpressionComplexityCheck() { 110 max = DEFAULT_MAX; 111 } 112 113 @Override 114 public int[] getDefaultTokens() { 115 return new int[] { 116 TokenTypes.CTOR_DEF, 117 TokenTypes.METHOD_DEF, 118 TokenTypes.EXPR, 119 TokenTypes.LAND, 120 TokenTypes.BAND, 121 TokenTypes.LOR, 122 TokenTypes.BOR, 123 TokenTypes.BXOR, 124 TokenTypes.COMPACT_CTOR_DEF, 125 }; 126 } 127 128 @Override 129 public int[] getRequiredTokens() { 130 return new int[] { 131 TokenTypes.CTOR_DEF, 132 TokenTypes.METHOD_DEF, 133 TokenTypes.EXPR, 134 TokenTypes.COMPACT_CTOR_DEF, 135 }; 136 } 137 138 @Override 139 public int[] getAcceptableTokens() { 140 return new int[] { 141 TokenTypes.CTOR_DEF, 142 TokenTypes.METHOD_DEF, 143 TokenTypes.EXPR, 144 TokenTypes.LAND, 145 TokenTypes.BAND, 146 TokenTypes.LOR, 147 TokenTypes.BOR, 148 TokenTypes.BXOR, 149 TokenTypes.COMPACT_CTOR_DEF, 150 }; 151 } 152 153 /** 154 * Setter to specify the maximum number of boolean operations allowed in one expression. 155 * 156 * @param max new maximum allowed complexity. 157 * @since 3.4 158 */ 159 public void setMax(int max) { 160 this.max = max; 161 } 162 163 @Override 164 public void visitToken(DetailAST ast) { 165 switch (ast.getType()) { 166 case TokenTypes.CTOR_DEF: 167 case TokenTypes.METHOD_DEF: 168 case TokenTypes.COMPACT_CTOR_DEF: 169 visitMethodDef(ast); 170 break; 171 case TokenTypes.EXPR: 172 visitExpr(); 173 break; 174 case TokenTypes.BOR: 175 if (!isPipeOperator(ast) && !isPassedInParameter(ast)) { 176 context.visitBooleanOperator(); 177 } 178 break; 179 case TokenTypes.BAND: 180 case TokenTypes.BXOR: 181 if (!isPassedInParameter(ast)) { 182 context.visitBooleanOperator(); 183 } 184 break; 185 case TokenTypes.LAND: 186 case TokenTypes.LOR: 187 context.visitBooleanOperator(); 188 break; 189 default: 190 throw new IllegalArgumentException("Unknown type: " + ast); 191 } 192 } 193 194 /** 195 * Checks if logical operator is part of constructor or method call. 196 * 197 * @param logicalOperator logical operator 198 * @return true if logical operator is part of constructor or method call 199 */ 200 private static boolean isPassedInParameter(DetailAST logicalOperator) { 201 return logicalOperator.getParent().getParent().getType() == TokenTypes.ELIST; 202 } 203 204 /** 205 * Checks if {@link TokenTypes#BOR binary OR} is applied to exceptions 206 * in 207 * <a href="https://docs.oracle.com/javase/specs/jls/se8/html/jls-14.html#jls-14.20"> 208 * multi-catch</a> (pipe-syntax). 209 * 210 * @param binaryOr {@link TokenTypes#BOR binary or} 211 * @return true if binary or is applied to exceptions in multi-catch. 212 */ 213 private static boolean isPipeOperator(DetailAST binaryOr) { 214 return binaryOr.getParent().getType() == TokenTypes.TYPE; 215 } 216 217 @Override 218 public void leaveToken(DetailAST ast) { 219 switch (ast.getType()) { 220 case TokenTypes.CTOR_DEF: 221 case TokenTypes.METHOD_DEF: 222 case TokenTypes.COMPACT_CTOR_DEF: 223 leaveMethodDef(); 224 break; 225 case TokenTypes.EXPR: 226 leaveExpr(ast); 227 break; 228 default: 229 // Do nothing 230 } 231 } 232 233 /** 234 * Creates new context for a given method. 235 * 236 * @param ast a method we start to check. 237 */ 238 private void visitMethodDef(DetailAST ast) { 239 contextStack.push(context); 240 final boolean check = !CheckUtil.isEqualsMethod(ast); 241 context = new Context(check); 242 } 243 244 /** Removes old context. */ 245 private void leaveMethodDef() { 246 context = contextStack.pop(); 247 } 248 249 /** Creates and pushes new context. */ 250 private void visitExpr() { 251 contextStack.push(context); 252 context = new Context(context.isChecking()); 253 } 254 255 /** 256 * Restores previous context. 257 * 258 * @param ast expression we leave. 259 */ 260 private void leaveExpr(DetailAST ast) { 261 context.checkCount(ast); 262 context = contextStack.pop(); 263 } 264 265 /** 266 * Represents context (method/expression) in which we check complexity. 267 * 268 */ 269 private final class Context { 270 271 /** 272 * Should we perform check in current context or not. 273 * Usually false if we are inside equals() method. 274 */ 275 private final boolean checking; 276 /** Count of boolean operators. */ 277 private int count; 278 279 /** 280 * Creates new instance. 281 * 282 * @param checking should we check in current context or not. 283 */ 284 private Context(boolean checking) { 285 this.checking = checking; 286 } 287 288 /** 289 * Getter for checking property. 290 * 291 * @return should we check in current context or not. 292 */ 293 public boolean isChecking() { 294 return checking; 295 } 296 297 /** Increases operator counter. */ 298 public void visitBooleanOperator() { 299 ++count; 300 } 301 302 /** 303 * Checks if we violate maximum allowed complexity. 304 * 305 * @param ast a node we check now. 306 */ 307 public void checkCount(DetailAST ast) { 308 if (checking && count > max) { 309 final DetailAST parentAST = ast.getParent(); 310 311 log(parentAST, MSG_KEY, count, max); 312 } 313 } 314 315 } 316 317}