Explicit clearing of variables

Code review rules

Object parameter not cleared, Object variable not cleared, Object variable clearing violation, Array [parameter] not deallocated and Array deallocation violation are the problems discussed on this page.

You can use Project Analyzer to require explicit clearing of object variables, deallocation of dynamic arrays and releasing of Win API resource handles. This group of review rules, part of the problem detection feature, helps you point out possible resource leaks, memory that is kept allocated after use and objects that stay live too long.

Object variables: require explicit clearing
Dynamic array variables: require explicit deallocation
Variables storing API resource handles: require explicit release call (more about API leaks)

Object variables and dynamic arrays

Visual Basic automatically clears objects and deallocates arrays. In VB Classic, an object is destroyed when there are no more references to it. In .NET, an object is destroyed by a process called garbage collection. This process happens asynchronously. You can expect a .NET object to get destroyed after is not used any more, but you cannot determine the exact time when this happens.

Whether you use .NET or VB Classic, you have two approaches to variable clearing.

Rely on automatic clearing. You can leave the clearing to VB and wait until the variables fall out of scope. A local variable, as well as a parameter, goes out of scope when you exit the procedure. In VB.NET, a local variable may also get garbage collected when its value is no longer used in the procedure (which may be before procedure exit). An object-level variable goes out of scope when the object is destroyed. Other variables go out of scope when the program ends. - This way is easy but there is the threat that your objects are not released, your arrays are not deallocated, and you eventually consume more system resources than necessary. The system doesn't free an object if a variable still holds a reference to it. Similarly, a dynamic array is not deallocated if it hasn't fallen out of scope. If so, you may have a resource leak at hand, and your program might even end up with an Out of memory error.
Require explicit clearing. To be sure, you clear your variables explicitly. This way you control the time when an object or an array has done its duties and can go.

Here are the ways to explicitly clear your variables:

Set obj = Nothing ' VB 3-6 object variables
obj = Nothing     ' VB.NET object variables
Erase myArray     ' Dynamic arrays

Next follows an explanation of the various options on the Clearing tab in Problem Options.

Selection of the variables to monitor

Require clearing of object variables. If this option is checked, all object variables (and arrays of object variables) are subject to the clearing requirement, except for auto-instantiated object variables declared As New in VB Classic.
Require clearing of auto-instantiated object variables. If this option is checked, all object variables (and arrays of object variables) declared As New in VB Classic are subject to the scrutiny.
Require deallocation of dynamic non-object arrays. If this option is checked, all dynamic arrays are subject to the deallocation rule. A dynamic array is one whose declaration doesn't define the size of the array. For dynamic array allocation, the following semantics are used: ReDim is the equivalent of assignment and Erase is the equivalent of clearing.
Require releasing of Win API resource handles. If this option is checked, all resource handle variables are subject to the API handle release rules. The following semantics are used: A handle create call is the equivalent of assignment and a handle release call is the equivalent of clearing.

Declare location and clearing rule

The clearing rules available are based on the scope of the variable in question. The declare locations Standard module and Class/form/structure are the more important ones. Procedure local variables and ByVal parameters can also be monitored for the sake of completeness.

No requirements. Ignore variables in this scope.
Require clearing. Require one clearing statement for each variable. It can be anywhere.
Require clearing inside module/class/form/structure. Require one clearing statement for each variable. It must be inside the same module, class, form or structure where the variable is declared. That is, the declarer must take care of the clearing.
Require clearing at destruction/unload. Require one clearing statement for each variable. The clearing statement must exist either in the destructor (.NET Finalize method), Form_Unload or Class_Terminate event (VB Classic). It can also exist in any procedure that these events call, provided that the call tree stays inside the same class/form/structure.
Require clear count >= assignment count. Require at least one as many clearing statement for each variable as there are assignment statements. The statements can be located anywhere.

Local object variables in .NET. Due to the nature of garbage collection (GC) in .NET, you may want to avoid explicit clearing of local object variables while requiring clearing for non-local ones. A local variable is subject to garbage collection after the line where it is mentioned the last time. After this line it's dead to .NET and ready to be garbage collected. If you explicitly clear the variable at the end of a long procedure you may actually be keeping it alive for a longer time than expected. By letting .NET handle the clearing of local objects you may end up with more efficient GC.

Exceptions

The following variables are not monitored: Static arrays. Object fields in user-defined Types (VB Classic). Variants in VB Classic and Objects in .NET, as they may contain non-object values. String variables, even though it makes sense to clear string variables to deallocate memory. Properties are not monitored either.

Comment directive