Categories

My 10 best practices leading to the Scripting Games 2012 – Part I

I wrote an article earlier in the year about how I got inspired into PowerShell. The enthusiasm has made me consider entering for the scripting games. At the moment I can’t tell how ready I am but having started reading to prepare I have a few things I have come to understand as best practices towards having a successful participation.

While it is possible for everyone to come out with that code that does something, there are several other factors that make one to stand out from the rest.

I title this “10 best practices for the scripting games”. I understand that there may be a lot more things to be aware of but the point here is not to attempt to highlight everything in PowerShell that needs to be addressed but to summarize my learning points into 10 handy notes while preparing.

In this two-part write-up I focus on the following:

Annotate your script

Accept input by pipeline

Use CmdletBinding

Use Comment Based Help

Keep it simple (KISS)

Support the enterprise

Manage the errors

Use native PowerShell commands

Output objects

Answer the question

Annotate your script

One of the major reasons for participating in a competition like this is to be able to produce tools that will be useful at work. This means that either you will be using by yourself or giving out to colleagues to use. The code will always require to be reviewed, either to improve functionality, or to add more. It is important that when you pick up the code to review you know and understand exactly what the code was originally designed to do.

Let your code outlive you. In your organization you will move to other roles and will not be managing codes anymore or out of the company. If someone, your successor, or colleague, or someone you mentor happens to review that code he should be able to do something with it.

The learning point for me here is how every line of code seems to have a statement explaining its purpose. Jeff Hicks has written on several aspect of PowerShell and his blog on jdhitsolutions.com/blog forms a great resource for both experienced PowerShell users, and beginners.

Accept pipeline input

The Scripting Guy in his last interview with PowerScripting podcast used the analogy of a mechanical tool he buys from a store to use. When you go to the store to buy this tool, you expect it to work straight out for the box. You have the object you want to use it on and you have expected results. It is completely unimportant to you at that moment what the tool is made of. Understandably if you are that savvy you want to know more about the specs, the physical makeup of the device, etc., but how many people really do that? The bottom line is that anyone taking that tool throws in his input and expects an output.

Whenever we use native PowerShell cmdlets we take for granted that these will be able to take in a single input or a collection of inputs from the pipeline, process them, and produce results. And in most cases, they do. As for what the expected results should be, the section on outputting objects discusses this. However it is important to understand that some of the best scripts will sit in the middle while ingesting objects (or stings) from the pipeline and spitting objects as outputs to be used further down the pipeline – something similar to a factory process.

PowerShell’s advanced function makes provision for this by providing the “accepts input by pipeline” option in the param block. Utilizing this contributes to producing a function that behaves like a native cmdlets.

Use CmdletBinding Attribute

By definition, CmdletBinding “declares a function that acts similar to a compiled cmdlet”.

One of the greatest attributes of PowerShell is the consistency in structure. It just makes sense that whenever we write our scripts we attempt to make them look and feel and act as close to native cmdlets as possible, as already discussed in the previous section.

CmdletBinding automatically provides the function with parameters like –Verbose, -Debug, -ErrorVariable, -ErrorAction commonly called as common parameters.

In addition, including “ShouldProcess” and setting that to $true gives us the ability to include -WhatIf and -Confirm to our script.

Use comment-based help

There is a difference between the comments you write in the script as annotations and comment-based help used for developing the help text for your script. While the ordinary comments, with‘#’ at the beginning of a new-line is used to help you or any other person reading the code in the future, comment based help extends this to actually providing a help file for your function..

Again including this in you script ensures allows people to use get-help to understand how the script works and how it can be used – further making the script to behave like a native cmdlet.

Keep it simple (KISS)

The most efficient codes are not necessarily the most complex. On the contrary when the code is simple and straightforward, it is easier to read, execute, and review; it also runs more efficiently, etc.

I came across the following two codes while looking for a simple solution – number of mailboxes per database.

Like this:

About the author: Ifiok Moses

I have over the past 10 years I have had experiences in Network and System Administration within and outside the US. I have interests in Exchange and the Windows Server and of course PowerShell (to support them). I am currently on Contract with BluePoint Data. Though I plan to I am not yet blogging, my twitter handle is @mifiok.