DCL14-J. Minimize the scope of variables

Scope minimization helps developers to avoid common programming errors, improves code readability by connecting the declaration and actual use of a variable, and improves maintainability because unused variables are more easily detected and removed.

Noncompliant Code Example

This noncompliant code example shows a variable that is declared outside the for loop. This reduces reusability because the value of the loop index i is modified by the for statement. Consider, for example, the case when this code snippet is copied and pasted with the intent to use a different index j. If the index variable change were omitted, the new loop would then attempt to iterate over index i. Unexpected behavior can follow because i remains in scope.

public class Scope {
  public static void main(String[] args) {
    int i = 0;
    for (i = 0; i < 10; i++) {
      // Do operations
    }
  }
}

It should be noted that this code is noncompliant because i is not used outside the for loop. The variable i would need to be declared local to the method if, for example, the loop contained a break statement and the value of i was inspected outside the loop.

Compliant Solution

Minimize the scope of variables where possible, for example, by declaring loop indices within the for statement.

public class Scope {
  public static void main(String[] args) {
    for (int i = 0; i < 10; i++) { //contains declaration
      // Do operations
    }
  }
}

Noncompliant Code Example

This noncompliant code example shows a variable count that is declared outside the counter method, although the variable is not used outside the counter method. This reduces the reusability of the method because count variable would need to be redefined in the new context.

public class Foo {
  private int count;
  static private final int MAX_COUNT;

  public void counter() {
    count = 0;
    while (condition()) {
      /* ... */
      if (count++ > MAX_COUNT) return;
    }
  }

  /* No other method references count */
  /* but several other methods reference MAX_COUNT */
}

Compliant Solution

In this compliant solution, the count field is declared local to the counter method.

public class Foo {
  static private final int MAX_COUNT;

  public void counter() {
    int count = 0;
    while (condition()) {
      /* ... */
      if (count++ > MAX_COUNT) return;
    }
  }

  /* No other method references count */
  /* but several other methods reference MAX_COUNT */
}

Risk Assessment

Do not use a larger scope than necessary because it will result in less reliable code.

Automated Detection

Detecting local variables that are declared in a larger scope than is required by the as-written code is straightforward and can avoid any possibility of false positives.

Detecting multiple for statements that use the same index variable is straightforward; it will produce false positives in the unusual case where this was intended by the programmer.

Related Guidelines

C Secure Coding Standard: "DCL19-C. Minimize the scope of variables and functions"

C++ Secure Coding Standard: "DCL07-CPP. Minimize the scope of variables and methods"

Bibliography

DCL13-J. Avoid cyclic dependencies between packages      01. Declarations and Initialization (DCL)      DCL15-J. Do not shadow or obscure identifiers in subscopes