Scope Helps Determine Level of Documentation Needed

There are many kinds of variables - local variables, parameters, member variables, global variables, etc. Even though variables are some of the simplest symbols that can exist in code, many of them are worth documenting.

In general, the larger the “scope” a variable has or the more clearly it forms an “interface”, the more it needs explicit documentation.

Some local variables within a function may need some regular (non-documentation generator style) comments for odd quirks. But in general, local variables don’t need more sophisticated documentation like other kinds of variables - they cover a smaller "surface area" of code a maintenance programmer may need to understand.

Parameters should be documented as they form important interfaces to functions - programmers using the functions need to understand the parameters.

Member variables (also known as “fields” or “attributes”) also should have documentation as they are effectively interfaces to a class. This is especially true if they are public, but even private member variables are an “interface” a maintenance programmer needs to understand. “Properties” in some programming languages are similar to member variables and thus warrant similar documentation.

Global variables should definitely be documented. By virtue of being at a "global" scope (outside of a specific class/function), that inherently makes a symbol more exposed, making it part of an API that maintenance programmers may need to understand and use. Therefore, any "global" symbols should be individually documented.

“Constants” are essentially the same as other kinds of variables. They should have documentation corresponding to their scope.

Tips for Documenting Variables with Larger Scopes

The following sections contain tips on documenting variables that have larger scopes than typical local variables: