Coding Strategies to Minimize Noise

The following simple code changes eliminate false-positive results and make your code easier to interpret and maintain:

• Add parentheses to clarify precedence, even when it is not required.

• Initialize variables in the statement in which you declare them.

• Replace explicit tests for STATUS_SUCCESS with the NT_SUCCESS macro. Similarly, use SUCCEEDED and FAILED with HRESULT values.

• Use assertions to make assumptions explicit. For example, to eliminate warnings about uninitialized variables that are initialized in a loop or outside of the function, add an assertion to declare that the path in which the variable is left uninitialized is impossible.

• Eliminate ambiguity. For example, if a variable is initialized inside a loop that might never be executed, structure the loop so that it is always executed at least one time or initialize the variable before the loop starts.

• Eliminate redundant function calls. For example, if a function return value is used to determine when to hold or release a resource, such as a lock, structure the code so that only one function call is necessary. Consider the following pseudocode:

  if (ShouldILock(...))
  {
  /* take a lock */
  }
  /* do something */
  
  if (ShouldILock(...))
  {
  /*release the lock */
  }
  

  In this situation, PREfast for Drivers cannot tell if the function ShouldILock() returns the same value with each call (in principle, the function could be a random number generator). Consequently, PFD will often complain about locks that are held and not released, and also about locks that are released without being held. If ShouldILock() will always return the same value, you could re-write the code as follows:

  BOOL NeedLock = ShouldILock(...);
  if (NeedLock)
  {
   /* take a lock */
  }
   / * do something */
  
  if (NeedLock)
  {
  /* release the lock */
  }
  

  This rewritten pseudocode is more efficient (there is only one function call), and should be clearer to someone reviewing the code. It also helps PFD to do its analysis correctly. If the function ShouldILock() does not always return the same value, the PFD has found a bug that should be fixed.

• Use function type declarations, (also called function role types) to make the function type of a function explicit. For an example, see Example 5: Inferred Purpose Based on Function Characteristics. For more information, see Declaring Functions Using Function Role Type Declarations.

Noise can be valuable, because it often identifies the programmer's assumptions. For example, if a variable is initialized in a loop, PREfast for Drivers considers the possibility that the loop is never executed. Even if this assumption is false, it might be helpful to add an assertion to make the assumption explicit and to take advantage of the notification provided by the checked build, in case the assumption is false and thus the assertion fails.

Because too much caution can be counterproductive, PREfast for Drivers supports filters and pragma warning directives to control the generation of particular warnings. Although filters and warning pragma statements are effective methods of reducing noise, many driver developers prefer not to use them because they can hide and suppress actual errors.

 

 

Send comments about this topic to Microsoft

Build date: 5/3/2011