Local Variables Defined And Used On One Page

Pattern: Local Variables Defined and Used on One Page

...this pattern helps complete the SimplyUnderstoodCode pattern; it settles part of the question of how to make the use of local variables understandable.

* * *

Local variables hold local state and serve as a means to abbreviate certain parts of the computation or to prevent computations from being repeated causing inefficiency or incorrectness. Frequently local variables disorient people reading the code.

You are writing a piece of code that requires local variables to hold temporary results. The code will be in use for a long time with relatively infrequent attention for maintenance. You expect that by the time you go back to the code it will be unfamiliar or else someone who has never seen it before will be working on it.

People need to stare at code in order to understand it well enough to feel secure making changes to it; understanding the role and uses of a local variable is central to this understanding. People understand best things read top to bottom.

Therefore, Lay out the definition of a local variable so that all of its uses are visible on one page of a typical screen or window size for the developers who might need to work on the code. Ideally the definition of the local variable will be above its use or reference.

* * *

This won't work well if the variable is assigned multiple times within the visible field, and it will work even worse if it is assigned multiple times partly within and partly outside the visible field. See the pattern AssignVariablesOnce.

There's an assumption here that the routine is bigger than a page. This is probably a bad idea in itself. If the function fits on a page, all its local variables will on a page also.

Sometimes the local variables are the reason the function has got so big. That is, you can't split it into smaller functions because all the parts of it need access to local variables. Some techniques for dealing with that situation are discussed in WellFactoredCode.

If you write SideEffectFreeFunctions?, then local variables become mere caches, used for efficiency and clarity and without having any effect on correctness.

Frequently local variables disorient people reading the code -- this may be a sign you need to chose their names more carefully. Using a variable for intermediate results can split a complicated expression into simpler ones, and giving a name to a quantity helps explain what that quantity is. It is usually better to introduce variables than to write comments.

-- DaveHarris

This pattern is for languages such as C and Fortran, which cannot get anything done with 3-line functions. A better way to say the rule - a more inclusive way - is "give everything the narrowest scope possible." --PhlIp