Beautiful Code

Using Normalized Script Notation

With no conventions for naming variables, constants, and functions in administrative scripting, processes become untraceable because variables are not only value stores, they fulfill documentation tasks. When assigning identifiers, you can use conventions from general software development.

The problem of mandatory notation has existed since the first programs were developed. Normalization approaches relate to syntax and variable name components (i.e., to increase the readability of an identifier or derive the type and function of a value from the name).

Two solutions for script naming normalization – upper CamelCase and Hungarian notation – solve these two problems. Upper CamelCase assumes that names usually comprise composite components. If this is the case, each substring should begin with an uppercase letter (e.g., StrUser). Hungarian notation, conceived by Charles Simonyi, uses a prefix to describe the function or type of a variable. For example, the p prefix designates a pointer type, dn a domain, and rg a field.

These examples alone illustrate the problem of a clear classification of type. Does "type" mean the data type or the function in the program? Because this cannot be answered unequivocally, Hungarian notation has branched off into two separate directions: Apps Hungarian notation as a functional approach and Systems Hungarian notation as a data type-specific declaration. These two approaches are not practicable for the development of scripts in PowerShell because of their disadvantages:

• The prefix is difficult to read because of difficulties in separating the two parts of a name.
• Apps Hungarian contains old-fashioned C-style data types (e.g., w for word).
• Type changes in both systems would mean renaming.
• The Systems Hungarian extension of the type system is too complex.

A script specification needs to be intuitive and easy to implement. Normalized script notation (NSN) is a combination of approaches. In principle, it differentiates between the processing of objects, structures, and value containers. A few basic data types are used when storing character strings or properties of an object (Table 1):

$StrToolPath = $StrActualScriptPath + "\tools\tools.ps1";
$BlnFlag = $FALSE;

In contrast, when objects are processed, the schematic type determines the prefix. In addition to the data storage type, the variable name also distinguishes between items and lists. After the two-digit prefixes for the provider type, l would display a list and i a single item. This standard could be used as a basis for working with Microsoft Active Directory:

• User list: AdUl
• User item: AdUi
• Group list: AdGl
• Group item: AdGi
• Computer list: AdCl
• Computer item: AdCi

Constants – memory areas that cannot be changed after the first assignment – are a special feature. Because PowerShell has no CONST keyword to distinguish constants from variables, complete capitalization of a constant (e.g., $STRADSPATH = "ou=Scripting,dc=Mydom,dc=com) is useful.

Pitfalls When Naming Functions

Functions make good scripts. The ability to encapsulate instructions and pass in parameters makes enterprise scripting both possible in the first place and reusable. However, errors in naming are a serious possibility. For example, if you want an application to find unneeded groups in Active Directory, PowerShell will need to access the LDAP metabase of the Active Directory objects to find valid data. If you encapsulate this access in a function named Get-AdObject, you have implemented the verb-noun naming principle. However, the Active Directory PowerShell module already has a cmdlet with that name. Once the function is loaded, it overwrites the cmdlet, with unwanted side effects. When processing identical commands, a cmdlet takes third place after aliases and functions.

To avoid duplication of names, you should use a label in a function name. For example, Verb-UD_Noun is a good scheme, where Verb stands for the actions known in PowerShell (see Get-Verb), UD_ stands for "user defined," and Noun is the administrative target.

Software Without Documentation Is Worthless

Script authors become painfully aware of inadequate documentation when they look at their work after a few months. A PowerShell script should contain two forms of documentation: comment-based help and inline. Comment-based help replaces the script header in other languages and relies on keywords in a comment block. The meaning of the individual sections can be retrieved by integrated help with

Get-Help about_Comment_Based_Help

in the PowerShell console. Descriptions, examples, and parameter usage should be the minimum content for comment-based help.

Comments within the source text always precede the statement that is to be explained. The content should be detailed and designed in such a way that co-workers who were not involved in the development of the program can also follow the operations in the script.