001//////////////////////////////////////////////////////////////////////////////// 002// checkstyle: Checks Java source code for adherence to a set of rules. 003// Copyright (C) 2001-2015 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.coding; 021 022import java.util.Arrays; 023 024import org.apache.commons.lang3.ArrayUtils; 025 026import com.puppycrawl.tools.checkstyle.api.Check; 027import com.puppycrawl.tools.checkstyle.api.DetailAST; 028import com.puppycrawl.tools.checkstyle.api.TokenTypes; 029import com.puppycrawl.tools.checkstyle.utils.CheckUtils; 030import com.puppycrawl.tools.checkstyle.utils.ScopeUtils; 031import com.puppycrawl.tools.checkstyle.utils.TokenUtils; 032 033/** 034 * <p> 035 * Checks that there are no <a href="https://en.wikipedia.org/wiki/Magic_number_%28programming%29"> 036 * "magic numbers"</a> where a magic 037 * number is a numeric literal that is not defined as a constant. 038 * By default, -1, 0, 1, and 2 are not considered to be magic numbers. 039 * </p> 040 * 041 * <p>Constant definition is any variable/field that has 'final' modifier. 042 * It is fine to have one constant defining multiple numeric literals within one expression: 043 * <pre> 044 * {@code static final int SECONDS_PER_DAY = 24 * 60 * 60; 045 * static final double SPECIAL_RATIO = 4.0 / 3.0; 046 * static final double SPECIAL_SUM = 1 + Math.E; 047 * static final double SPECIAL_DIFFERENCE = 4 - Math.PI; 048 * static final Border STANDARD_BORDER = BorderFactory.createEmptyBorder(3, 3, 3, 3); 049 * static final Integer ANSWER_TO_THE_ULTIMATE_QUESTION_OF_LIFE = new Integer(42);} 050 * </pre> 051 * 052 * <p>Check have following options: 053 * ignoreHashCodeMethod - ignore magic numbers in hashCode methods; 054 * ignoreAnnotation - ignore magic numbers in annotation declarations; 055 * ignoreFieldDeclaration - ignore magic numbers in field declarations. 056 * <p> 057 * To configure the check with default configuration: 058 * </p> 059 * <pre> 060 * <module name="MagicNumber"/> 061 * </pre> 062 * <p> 063 * results is following violations: 064 * </p> 065 * <pre> 066 * {@code 067 * {@literal @}MyAnnotation(6) // violation 068 * class MyClass { 069 * private field = 7; // violation 070 * 071 * void foo() { 072 * int i = i + 1; // no violation 073 * int j = j + 8; // violation 074 * } 075 * } 076 * } 077 * </pre> 078 * <p> 079 * To configure the check so that it checks floating-point numbers 080 * that are not 0, 0.5, or 1: 081 * </p> 082 * <pre> 083 * <module name="MagicNumber"> 084 * <property name="tokens" value="NUM_DOUBLE, NUM_FLOAT"/> 085 * <property name="ignoreNumbers" value="0, 0.5, 1"/> 086 * <property name="ignoreFieldDeclaration" value="true"/> 087 * <property name="ignoreAnnotation" value="true"/> 088 * </module> 089 * </pre> 090 * <p> 091 * results is following violations: 092 * </p> 093 * <pre> 094 * {@code 095 * {@literal @}MyAnnotation(6) // no violation 096 * class MyClass { 097 * private field = 7; // no violation 098 * 099 * void foo() { 100 * int i = i + 1; // no violation 101 * int j = j + (int)0.5; // no violation 102 * } 103 * } 104 * } 105 * </pre> 106 * <p> 107 * Config example of constantWaiverParentToken option: 108 * </p> 109 * <pre> 110 * <module name="MagicNumber"> 111 * <property name="constantWaiverParentToken" value="ASSIGN,ARRAY_INIT,EXPR, 112 * UNARY_PLUS, UNARY_MINUS, TYPECAST, ELIST, DIV, PLUS "/> 113 * </module> 114 * </pre> 115 * <p> 116 * result is following violation: 117 * </p> 118 * <pre> 119 * {@code 120 * class TestMethodCall { 121 * public void method2() { 122 * final TestMethodCall dummyObject = new TestMethodCall(62); //violation 123 * final int a = 3; // ok as waiver is ASSIGN 124 * final int [] b = {4, 5} // ok as waiver is ARRAY_INIT 125 * final int c = -3; // ok as waiver is UNARY_MINUS 126 * final int d = +4; // ok as waiver is UNARY_PLUS 127 * final int e = method(1, 2) // ELIST is there but violation due to METHOD_CALL 128 * final int x = 3 * 4; // violation 129 * final int y = 3 / 4; // ok as waiver is DIV 130 * final int z = 3 + 4; // ok as waiver is PLUS 131 * final int w = 3 - 4; // violation 132 * final int x = (int)(3.4); //ok as waiver is TYPECAST 133 * } 134 * } 135 * } 136 * </pre> 137 * @author Rick Giles 138 * @author Lars Kühne 139 * @author Daniel Solano Gómez 140 */ 141public class MagicNumberCheck extends Check { 142 143 /** 144 * A key is pointing to the warning message text in "messages.properties" 145 * file. 146 */ 147 public static final String MSG_KEY = "magic.number"; 148 149 /** 150 * The token types that are allowed in the AST path from the 151 * number literal to the enclosing constant definition. 152 */ 153 private int[] constantWaiverParentToken = { 154 TokenTypes.ASSIGN, 155 TokenTypes.ARRAY_INIT, 156 TokenTypes.EXPR, 157 TokenTypes.UNARY_PLUS, 158 TokenTypes.UNARY_MINUS, 159 TokenTypes.TYPECAST, 160 TokenTypes.ELIST, 161 TokenTypes.LITERAL_NEW, 162 TokenTypes.METHOD_CALL, 163 TokenTypes.STAR, 164 TokenTypes.DIV, 165 TokenTypes.PLUS, 166 TokenTypes.MINUS, 167 }; 168 169 /** The numbers to ignore in the check, sorted. */ 170 private double[] ignoreNumbers = {-1, 0, 1, 2}; 171 172 /** Whether to ignore magic numbers in a hash code method. */ 173 private boolean ignoreHashCodeMethod; 174 175 /** Whether to ignore magic numbers in annotation. */ 176 private boolean ignoreAnnotation; 177 178 /** Whether to ignore magic numbers in field declaration. */ 179 private boolean ignoreFieldDeclaration; 180 181 /** 182 * Constructor for MagicNumber Check. 183 * Sort the allowedTokensBetweenMagicNumberAndConstDef array for binary search. 184 */ 185 public MagicNumberCheck() { 186 Arrays.sort(constantWaiverParentToken); 187 } 188 189 @Override 190 public int[] getDefaultTokens() { 191 return getAcceptableTokens(); 192 } 193 194 @Override 195 public int[] getAcceptableTokens() { 196 return new int[] { 197 TokenTypes.NUM_DOUBLE, 198 TokenTypes.NUM_FLOAT, 199 TokenTypes.NUM_INT, 200 TokenTypes.NUM_LONG, 201 }; 202 } 203 204 @Override 205 public int[] getRequiredTokens() { 206 return ArrayUtils.EMPTY_INT_ARRAY; 207 } 208 209 @Override 210 public void visitToken(DetailAST ast) { 211 if (ignoreAnnotation && isChildOf(ast, TokenTypes.ANNOTATION)) { 212 return; 213 } 214 215 if (isInIgnoreList(ast) 216 || ignoreHashCodeMethod && isInHashCodeMethod(ast)) { 217 return; 218 } 219 220 final DetailAST constantDefAST = findContainingConstantDef(ast); 221 222 if (constantDefAST == null) { 223 if (!(ignoreFieldDeclaration && isFieldDeclaration(ast))) { 224 reportMagicNumber(ast); 225 } 226 } 227 else { 228 final boolean found = isMagicNumberExists(ast, constantDefAST); 229 if (found) { 230 reportMagicNumber(ast); 231 } 232 } 233 } 234 235 /** 236 * Is magic number some where at ast tree. 237 * @param ast ast token 238 * @param constantDefAST constant ast 239 * @return true if magic number is present 240 */ 241 private boolean isMagicNumberExists(DetailAST ast, DetailAST constantDefAST) { 242 boolean found = false; 243 DetailAST astNode = ast.getParent(); 244 while (astNode != constantDefAST) { 245 final int type = astNode.getType(); 246 if (Arrays.binarySearch(constantWaiverParentToken, type) < 0) { 247 found = true; 248 break; 249 } 250 astNode = astNode.getParent(); 251 } 252 return found; 253 } 254 255 /** 256 * Finds the constant definition that contains aAST. 257 * @param ast the AST 258 * @return the constant def or null if ast is not contained in a constant definition. 259 */ 260 private static DetailAST findContainingConstantDef(DetailAST ast) { 261 DetailAST varDefAST = ast; 262 while (varDefAST != null 263 && varDefAST.getType() != TokenTypes.VARIABLE_DEF 264 && varDefAST.getType() != TokenTypes.ENUM_CONSTANT_DEF) { 265 varDefAST = varDefAST.getParent(); 266 } 267 DetailAST constantDef = null; 268 269 // no containing variable definition? 270 if (varDefAST != null) { 271 // implicit constant? 272 if (ScopeUtils.isInInterfaceOrAnnotationBlock(varDefAST) 273 || varDefAST.getType() == TokenTypes.ENUM_CONSTANT_DEF) { 274 constantDef = varDefAST; 275 } 276 else { 277 // explicit constant 278 final DetailAST modifiersAST = varDefAST.findFirstToken(TokenTypes.MODIFIERS); 279 280 if (modifiersAST.branchContains(TokenTypes.FINAL)) { 281 constantDef = varDefAST; 282 } 283 } 284 } 285 return constantDef; 286 } 287 288 /** 289 * Reports aAST as a magic number, includes unary operators as needed. 290 * @param ast the AST node that contains the number to report 291 */ 292 private void reportMagicNumber(DetailAST ast) { 293 String text = ast.getText(); 294 final DetailAST parent = ast.getParent(); 295 DetailAST reportAST = ast; 296 if (parent.getType() == TokenTypes.UNARY_MINUS) { 297 reportAST = parent; 298 text = "-" + text; 299 } 300 else if (parent.getType() == TokenTypes.UNARY_PLUS) { 301 reportAST = parent; 302 text = "+" + text; 303 } 304 log(reportAST.getLineNo(), 305 reportAST.getColumnNo(), 306 MSG_KEY, 307 text); 308 } 309 310 /** 311 * Determines whether or not the given AST is in a valid hash code method. 312 * A valid hash code method is considered to be a method of the signature 313 * {@code public int hashCode()}. 314 * 315 * @param ast the AST from which to search for an enclosing hash code 316 * method definition 317 * 318 * @return {@code true} if {@code ast} is in the scope of a valid hash code method. 319 */ 320 private static boolean isInHashCodeMethod(DetailAST ast) { 321 boolean inHashCodeMethod = false; 322 323 // if not in a code block, can't be in hashCode() 324 if (ScopeUtils.isInCodeBlock(ast)) { 325 // find the method definition AST 326 DetailAST methodDefAST = ast.getParent(); 327 while (methodDefAST != null 328 && methodDefAST.getType() != TokenTypes.METHOD_DEF) { 329 methodDefAST = methodDefAST.getParent(); 330 } 331 332 if (methodDefAST != null) { 333 // Check for 'hashCode' name. 334 final DetailAST identAST = methodDefAST.findFirstToken(TokenTypes.IDENT); 335 336 if ("hashCode".equals(identAST.getText())) { 337 // Check for no arguments. 338 final DetailAST paramAST = methodDefAST.findFirstToken(TokenTypes.PARAMETERS); 339 // we are in a 'public int hashCode()' method! The compiler will ensure 340 // the method returns an 'int' and is public. 341 inHashCodeMethod = paramAST.getChildCount() == 0; 342 } 343 } 344 } 345 return inHashCodeMethod; 346 } 347 348 /** 349 * Decides whether the number of an AST is in the ignore list of this 350 * check. 351 * @param ast the AST to check 352 * @return true if the number of ast is in the ignore list of this check. 353 */ 354 private boolean isInIgnoreList(DetailAST ast) { 355 double value = CheckUtils.parseDouble(ast.getText(), ast.getType()); 356 final DetailAST parent = ast.getParent(); 357 if (parent.getType() == TokenTypes.UNARY_MINUS) { 358 value = -1 * value; 359 } 360 return Arrays.binarySearch(ignoreNumbers, value) >= 0; 361 } 362 363 /** 364 * Determines whether or not the given AST is field declaration. 365 * 366 * @param ast AST from which to search for an enclosing field declaration 367 * 368 * @return {@code true} if {@code ast} is in the scope of field declaration 369 */ 370 private static boolean isFieldDeclaration(DetailAST ast) { 371 DetailAST varDefAST = ast; 372 while (varDefAST != null 373 && varDefAST.getType() != TokenTypes.VARIABLE_DEF) { 374 varDefAST = varDefAST.getParent(); 375 } 376 377 // contains variable declaration 378 // and it is directly inside class declaration 379 return varDefAST != null 380 && varDefAST.getParent().getParent().getType() == TokenTypes.CLASS_DEF; 381 } 382 383 /** 384 * Sets the tokens which are allowed between Magic Number and defined Object. 385 * @param tokens The string representation of the tokens interested in 386 */ 387 public void setConstantWaiverParentToken(String... tokens) { 388 constantWaiverParentToken = new int[tokens.length]; 389 for (int i = 0; i < tokens.length; i++) { 390 constantWaiverParentToken[i] = TokenUtils.getTokenId(tokens[i]); 391 } 392 Arrays.sort(constantWaiverParentToken); 393 } 394 395 /** 396 * Sets the numbers to ignore in the check. 397 * BeanUtils converts numeric token list to double array automatically. 398 * @param list list of numbers to ignore. 399 */ 400 public void setIgnoreNumbers(double... list) { 401 if (list.length == 0) { 402 ignoreNumbers = ArrayUtils.EMPTY_DOUBLE_ARRAY; 403 } 404 else { 405 ignoreNumbers = new double[list.length]; 406 System.arraycopy(list, 0, ignoreNumbers, 0, list.length); 407 Arrays.sort(ignoreNumbers); 408 } 409 } 410 411 /** 412 * Set whether to ignore hashCode methods. 413 * @param ignoreHashCodeMethod decide whether to ignore 414 * hash code methods 415 */ 416 public void setIgnoreHashCodeMethod(boolean ignoreHashCodeMethod) { 417 this.ignoreHashCodeMethod = ignoreHashCodeMethod; 418 } 419 420 /** 421 * Set whether to ignore Annotations. 422 * @param ignoreAnnotation decide whether to ignore annotations 423 */ 424 public void setIgnoreAnnotation(boolean ignoreAnnotation) { 425 this.ignoreAnnotation = ignoreAnnotation; 426 } 427 428 /** 429 * Set whether to ignore magic numbers in field declaration. 430 * @param ignoreFieldDeclaration decide whether to ignore magic numbers 431 * in field declaration 432 */ 433 public void setIgnoreFieldDeclaration(boolean ignoreFieldDeclaration) { 434 this.ignoreFieldDeclaration = ignoreFieldDeclaration; 435 } 436 437 /** 438 * Determines if the given AST node has a parent node with given token type code. 439 * 440 * @param ast the AST from which to search for annotations 441 * @param type the type code of parent token 442 * 443 * @return {@code true} if the AST node has a parent with given token type. 444 */ 445 private static boolean isChildOf(DetailAST ast, int type) { 446 boolean result = false; 447 DetailAST node = ast; 448 do { 449 if (node.getType() == type) { 450 result = true; 451 } 452 node = node.getParent(); 453 } while (node != null && !result); 454 455 return result; 456 } 457}