Class VariableDeclarationUsageDistanceCheck
- All Implemented Interfaces:
Configurable
,Contextualizable
Checks the distance between declaration of variable and its first usage. Note : Variable declaration/initialization statements are not counted while calculating length.
-
Property
allowedDistance
- Specify distance between declaration of variable and its first usage. Values should be greater than 0. Type isint
. Default value is3
. -
Property
ignoreVariablePattern
- Define RegExp to ignore distance calculation for variables listed in this pattern. Type isjava.util.regex.Pattern
. Default value is""
. -
Property
validateBetweenScopes
- Allow to calculate the distance between declaration of variable and its first usage in the different scopes. Type isboolean
. Default value isfalse
. -
Property
ignoreFinal
- Allow to ignore variables with a 'final' modifier. Type isboolean
. Default value istrue
.
To configure the check with default config:
<module name="VariableDeclarationUsageDistance"/>
Example:
public class Test { public void foo1() { int num; // violation, distance = 4 final int PI; // OK, final variables not checked System.out.println("Statement 1"); System.out.println("Statement 2"); System.out.println("Statement 3"); num = 1; PI = 3.14; } public void foo2() { int a; // OK, used in different scope int b; // OK, used in different scope int count = 0; // OK, used in different scope { System.out.println("Inside inner scope"); a = 1; b = 2; count++; } } }
Check can detect a block of initialization methods. If a variable is used in such a block and there are no other statements after variable declaration, then distance = 1.
Case #1:
int minutes = 5; Calendar cal = Calendar.getInstance(); cal.setTimeInMillis(timeNow); cal.set(Calendar.SECOND, 0); cal.set(Calendar.MILLISECOND, 0); cal.set(Calendar.HOUR_OF_DAY, hh); cal.set(Calendar.MINUTE, minutes);
The distance for the variable "minutes" is 1 even though this variable is used in the fifth method's call.
Case #2:
int minutes = 5; Calendar cal = Calendar.getInstance(); cal.setTimeInMillis(timeNow); cal.set(Calendar.SECOND, 0); cal.set(Calendar.MILLISECOND, 0); System.out.println(cal); cal.set(Calendar.HOUR_OF_DAY, hh); cal.set(Calendar.MINUTE, minutes);
The distance for the variable "minutes" is 6 because there is one more expression (except the initialization block) between the declaration of this variable and its usage.
To configure the check to set allowed distance:
<module name="VariableDeclarationUsageDistance"> <property name="allowedDistance" value="4"/> </module>
Example:
public class Test { public void foo1() { int num; // OK, distance = 4 final int PI; // OK, final variables not checked System.out.println("Statement 1"); System.out.println("Statement 2"); System.out.println("Statement 3"); num = 1; PI = 3.14; } public void foo2() { int a; // OK, used in different scope int b; // OK, used in different scope int count = 0; // OK, used in different scope { System.out.println("Inside inner scope"); a = 1; b = 2; count++; } } }
To configure the check to ignore certain variables:
<module name="VariableDeclarationUsageDistance"> <property name="ignoreVariablePattern" value="^num$"/> </module>
This configuration ignores variables named "num".
Example:
public class Test { public void foo1() { int num; // OK, variable ignored final int PI; // OK, final variables not checked System.out.println("Statement 1"); System.out.println("Statement 2"); System.out.println("Statement 3"); num = 1; PI = 3.14; } public void foo2() { int a; // OK, used in different scope int b; // OK, used in different scope int count = 0; // OK, used in different scope { System.out.println("Inside inner scope"); a = 1; b = 2; count++; } } }
To configure the check to force validation between scopes:
<module name="VariableDeclarationUsageDistance"> <property name="validateBetweenScopes" value="true"/> </module>
Example:
public class Test { public void foo1() { int num; // violation, distance = 4 final int PI; // OK, final variables not checked System.out.println("Statement 1"); System.out.println("Statement 2"); System.out.println("Statement 3"); num = 1; PI = 3.14; } public void foo2() { int a; // OK, distance = 2 int b; // OK, distance = 3 int count = 0; // violation, distance = 4 { System.out.println("Inside inner scope"); a = 1; b = 2; count++; } } }
To configure the check to check final variables:
<module name="VariableDeclarationUsageDistance"> <property name="ignoreFinal" value="false"/> </module>
Example:
public class Test { public void foo1() { int num; // violation, distance = 4 final int PI; // violation, distance = 5 System.out.println("Statement 1"); System.out.println("Statement 2"); System.out.println("Statement 3"); num = 1; PI = 3.14; } public void foo2() { int a; // OK, used in different scope int b; // OK, used in different scope int count = 0; // OK, used in different scope { System.out.println("Inside inner scope"); a = 1; b = 2; count++; } } }
Parent is com.puppycrawl.tools.checkstyle.TreeWalker
Violation Message Keys:
-
variable.declaration.usage.distance
-
variable.declaration.usage.distance.extend
- Since:
- 5.8
-
Nested Class Summary
Nested classes/interfaces inherited from class com.puppycrawl.tools.checkstyle.api.AutomaticBean
AutomaticBean.OutputStreamOptions
-
Field Summary
FieldsModifier and TypeFieldDescriptionprivate int
Specify distance between declaration of variable and its first usage.private static final int
Default value of distance between declaration of variable and its first usage.private boolean
Allow to ignore variables with a 'final' modifier.private Pattern
Define RegExp to ignore distance calculation for variables listed in this pattern.static final String
Warning message key.static final String
Warning message key.private boolean
Allow to calculate the distance between declaration of variable and its first usage in the different scopes. -
Constructor Summary
Constructors -
Method Summary
Modifier and TypeMethodDescriptioncalculateDistanceBetweenScopes
(DetailAST ast, DetailAST variable) Calculates distance between declaration of variable and its first usage in multiple scopes.calculateDistanceInSingleScope
(DetailAST semicolonAst, DetailAST variableIdentAst) Calculates distance between declaration of variable and its first usage in single scope.int[]
The configurable token set.int[]
Returns the default token a check is interested in.private static int
getDistToVariableUsageInChildNode
(DetailAST childNode, DetailAST varIdent, int currentDistToVarUsage) Returns the distance to variable usage for in the child node.private static DetailAST
Helper method for getFirstNodeInsideSwitchBlock to return the first CASE_GROUP or SWITCH_RULE ast.private static DetailAST
getFirstNodeInsideForWhileDoWhileBlocks
(DetailAST block, DetailAST variable) Gets first Ast node inside FOR, WHILE or DO-WHILE blocks if variable usage is met only inside the block (not in its declaration!).private static DetailAST
getFirstNodeInsideIfBlock
(DetailAST block, DetailAST variable) Gets first Ast node inside IF block if variable usage is met only inside the block (not in its declaration!).private static DetailAST
getFirstNodeInsideSwitchBlock
(DetailAST block, DetailAST variable) Gets first Ast node inside SWITCH block if variable usage is met only inside the block (not in its declaration!).private static DetailAST
getFirstNodeInsideTryCatchFinallyBlocks
(DetailAST block, DetailAST variable) Gets first Ast node inside TRY-CATCH-FINALLY blocks if variable usage is met only inside the block (not in its declaration!).private static String
getInstanceName
(DetailAST methodCallAst) Get name of instance whose method is called.int[]
The tokens that this check must be registered for.private static boolean
Checks if Ast node contains given element.private static boolean
isInitializationSequence
(DetailAST variableUsageAst, String variableName) Processes statements until usage of variable to detect sequence of initialization methods.private static boolean
isVariableInOperatorExpr
(DetailAST operator, DetailAST variable) Checks if variable is in operator declaration.private boolean
isVariableMatchesIgnorePattern
(String variable) Checks if entrance variable is contained in ignored pattern.searchVariableUsageExpressions
(DetailAST variableAst, DetailAST statementAst) Searches variable usages starting from specified statement.void
setAllowedDistance
(int allowedDistance) Setter to specify distance between declaration of variable and its first usage.void
setIgnoreFinal
(boolean ignoreFinal) Setter to allow to ignore variables with a 'final' modifier.void
setIgnoreVariablePattern
(Pattern pattern) Setter to define RegExp to ignore distance calculation for variables listed in this pattern.void
setValidateBetweenScopes
(boolean validateBetweenScopes) Setter to allow to calculate the distance between declaration of variable and its first usage in the different scopes.void
visitToken
(DetailAST ast) Called to process a token.Methods inherited from class com.puppycrawl.tools.checkstyle.api.AbstractCheck
beginTree, clearViolations, destroy, finishTree, getFileContents, getLine, getLineCodePoints, getLines, getTabWidth, getTokenNames, getViolations, init, isCommentNodesRequired, leaveToken, log, log, log, setFileContents, setTabWidth, setTokens
Methods inherited from class com.puppycrawl.tools.checkstyle.api.AbstractViolationReporter
finishLocalSetup, getCustomMessages, getId, getMessageBundle, getSeverity, getSeverityLevel, setId, setSeverity
Methods inherited from class com.puppycrawl.tools.checkstyle.api.AutomaticBean
configure, contextualize, getConfiguration, setupChild
-
Field Details
-
MSG_KEY
Warning message key.- See Also:
-
MSG_KEY_EXT
Warning message key.- See Also:
-
DEFAULT_DISTANCE
private static final int DEFAULT_DISTANCEDefault value of distance between declaration of variable and its first usage.- See Also:
-
allowedDistance
private int allowedDistanceSpecify distance between declaration of variable and its first usage. Values should be greater than 0. -
ignoreVariablePattern
Define RegExp to ignore distance calculation for variables listed in this pattern. -
validateBetweenScopes
private boolean validateBetweenScopesAllow to calculate the distance between declaration of variable and its first usage in the different scopes. -
ignoreFinal
private boolean ignoreFinalAllow to ignore variables with a 'final' modifier.
-
-
Constructor Details
-
VariableDeclarationUsageDistanceCheck
public VariableDeclarationUsageDistanceCheck()
-
-
Method Details
-
setAllowedDistance
public void setAllowedDistance(int allowedDistance) Setter to specify distance between declaration of variable and its first usage. Values should be greater than 0.- Parameters:
allowedDistance
- Allowed distance between declaration of variable and its first usage.
-
setIgnoreVariablePattern
Setter to define RegExp to ignore distance calculation for variables listed in this pattern.- Parameters:
pattern
- a pattern.
-
setValidateBetweenScopes
public void setValidateBetweenScopes(boolean validateBetweenScopes) Setter to allow to calculate the distance between declaration of variable and its first usage in the different scopes.- Parameters:
validateBetweenScopes
- Defines if allow to calculate distance between declaration of variable and its first usage in different scopes or not.
-
setIgnoreFinal
public void setIgnoreFinal(boolean ignoreFinal) Setter to allow to ignore variables with a 'final' modifier.- Parameters:
ignoreFinal
- Defines if ignore variables with 'final' modifier or not.
-
getDefaultTokens
public int[] getDefaultTokens()Description copied from class:AbstractCheck
Returns the default token a check is interested in. Only used if the configuration for a check does not define the tokens.- Specified by:
getDefaultTokens
in classAbstractCheck
- Returns:
- the default tokens
- See Also:
-
getAcceptableTokens
public int[] getAcceptableTokens()Description copied from class:AbstractCheck
The configurable token set. Used to protect Checks against malicious users who specify an unacceptable token set in the configuration file. The default implementation returns the check's default tokens.- Specified by:
getAcceptableTokens
in classAbstractCheck
- Returns:
- the token set this check is designed for.
- See Also:
-
getRequiredTokens
public int[] getRequiredTokens()Description copied from class:AbstractCheck
The tokens that this check must be registered for.- Specified by:
getRequiredTokens
in classAbstractCheck
- Returns:
- the token set this must be registered for.
- See Also:
-
visitToken
Description copied from class:AbstractCheck
Called to process a token.- Overrides:
visitToken
in classAbstractCheck
- Parameters:
ast
- the token to process
-
getInstanceName
Get name of instance whose method is called.- Parameters:
methodCallAst
- DetailAST of METHOD_CALL.- Returns:
- name of instance.
-
isInitializationSequence
Processes statements until usage of variable to detect sequence of initialization methods.- Parameters:
variableUsageAst
- DetailAST of expression that uses variable named variableName.variableName
- name of considered variable.- Returns:
- true if statements between declaration and usage of variable are initialization methods.
-
calculateDistanceInSingleScope
private static Map.Entry<DetailAST,Integer> calculateDistanceInSingleScope(DetailAST semicolonAst, DetailAST variableIdentAst) Calculates distance between declaration of variable and its first usage in single scope.- Parameters:
semicolonAst
- Regular node of Ast which is checked for content of checking variable.variableIdentAst
- Variable which distance is calculated for.- Returns:
- entry which contains expression with variable usage and distance.
-
getDistToVariableUsageInChildNode
private static int getDistToVariableUsageInChildNode(DetailAST childNode, DetailAST varIdent, int currentDistToVarUsage) Returns the distance to variable usage for in the child node.- Parameters:
childNode
- child node.varIdent
- variable variable identifier.currentDistToVarUsage
- current distance to the variable usage.- Returns:
- the distance to variable usage for in the child node.
-
calculateDistanceBetweenScopes
private static Map.Entry<DetailAST,Integer> calculateDistanceBetweenScopes(DetailAST ast, DetailAST variable) Calculates distance between declaration of variable and its first usage in multiple scopes.- Parameters:
ast
- Regular node of Ast which is checked for content of checking variable.variable
- Variable which distance is calculated for.- Returns:
- entry which contains expression with variable usage and distance.
-
searchVariableUsageExpressions
private static Map.Entry<List<DetailAST>,Integer> searchVariableUsageExpressions(DetailAST variableAst, DetailAST statementAst) Searches variable usages starting from specified statement.- Parameters:
variableAst
- Variable that is used.statementAst
- DetailAST to start searching from.- Returns:
- entry which contains list with found expressions that use the variable and distance from specified statement to first found expression.
-
getFirstNodeInsideForWhileDoWhileBlocks
private static DetailAST getFirstNodeInsideForWhileDoWhileBlocks(DetailAST block, DetailAST variable) Gets first Ast node inside FOR, WHILE or DO-WHILE blocks if variable usage is met only inside the block (not in its declaration!).- Parameters:
block
- Ast node represents FOR, WHILE or DO-WHILE block.variable
- Variable which is checked for content in block.- Returns:
- If variable usage is met only inside the block (not in its declaration!) then return the first Ast node of this block, otherwise - null.
-
getFirstNodeInsideIfBlock
Gets first Ast node inside IF block if variable usage is met only inside the block (not in its declaration!).- Parameters:
block
- Ast node represents IF block.variable
- Variable which is checked for content in block.- Returns:
- If variable usage is met only inside the block (not in its declaration!) then return the first Ast node of this block, otherwise - null.
-
getFirstNodeInsideSwitchBlock
Gets first Ast node inside SWITCH block if variable usage is met only inside the block (not in its declaration!).- Parameters:
block
- Ast node represents SWITCH block.variable
- Variable which is checked for content in block.- Returns:
- If variable usage is met only inside the block (not in its declaration!) then return the first Ast node of this block, otherwise - null.
-
getFirstCaseGroupOrSwitchRule
Helper method for getFirstNodeInsideSwitchBlock to return the first CASE_GROUP or SWITCH_RULE ast.- Parameters:
block
- the switch block to check.- Returns:
- DetailAST of the first CASE_GROUP or SWITCH_RULE.
-
getFirstNodeInsideTryCatchFinallyBlocks
private static DetailAST getFirstNodeInsideTryCatchFinallyBlocks(DetailAST block, DetailAST variable) Gets first Ast node inside TRY-CATCH-FINALLY blocks if variable usage is met only inside the block (not in its declaration!).- Parameters:
block
- Ast node represents TRY-CATCH-FINALLY block.variable
- Variable which is checked for content in block.- Returns:
- If variable usage is met only inside the block (not in its declaration!) then return the first Ast node of this block, otherwise - null.
-
isVariableInOperatorExpr
Checks if variable is in operator declaration. For instance:boolean b = true; if (b) {...}
Variable 'b' is in declaration of operator IF.- Parameters:
operator
- Ast node which represents operator.variable
- Variable which is checked for content in operator.- Returns:
- true if operator contains variable in its declaration, otherwise - false.
-
isChild
Checks if Ast node contains given element.- Parameters:
parent
- Node of AST.ast
- Ast element which is checked for content in Ast node.- Returns:
- true if Ast element was found in Ast node, otherwise - false.
-
isVariableMatchesIgnorePattern
Checks if entrance variable is contained in ignored pattern.- Parameters:
variable
- Variable which is checked for content in ignored pattern.- Returns:
- true if variable was found, otherwise - false.
-