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
------
See Also: NestedFunctions
----
CategoryCodingIssues