Reflections on the PowerShell Scripting Games

talkbubbleDuring the most recent PowerShell Scripting Games, I was fortunate enough to be one of the judges. Now that the games have concluded I thought I’d share my reflections on the entries. Naturally these are merely my opinions but they are drawn from years of experience with PowerShell and almost 25 years as an IT Pro. All I can hope is that you’ll consider some of these things on your next PowerShell development project.

Let me also be clear, for those of you still new to PowerShell, that when using it interactively at a PowerShell prompt, anything goes if it helps you get the job done efficiently. But when you are creating a scripted PowerShell solution, something that will live on, then the guidelines are a little different.

It is true that the challenges for this past set of games were complex. Frankly, I’m not sure how I would have even started on a few of them. That said, we’re still talking about PowerShell scripts in the end. One thing that struck me on the entries I judged, was how often I felt I was reading source code for a Visual Studio project and not a PowerShell script. On one hand that could be considered a good thing: PowerShell is flexible enough to create anything from basic scripts to the types of entries I reviewed. But then again, if you have the technical chops to come up with code like I read, you probably could create a “real” set of compiled tools. At some point in your development process you might ask yourself if you are creating a PowerShell script or have moved beyond and maybe a script isn’t the right solution. Yes, the game entries needed to be PowerShell scripts and modules but what about what you’re working on?

Even so, this brings me to my next point: maintainability. The best way to test this is to hand your script files to someone else, ideally with a little less PowerShell knowledge than you, and see if they can understand what your scripts do and how. Many of the entries I read were sprawling, complicated masses of functions and scripts and .NET code. I was challenged in many cases to try and figure out what was going on. If *I* have to struggle to figure out how all the pieces of your script or module work, think about your co-worker who gets handed your solution to maintain or troubleshoot when you get promoted. Or it might be you coming back to it in 6 months.

There is no penalty for comments. I encourage beginners to write the comments first so that they can organize and plan their work. For a module, you can also write your own About help topics. In my opinion, information like this is just as important as the PowerShell commands you are using.

Lastly, I have the usual concerns about syntax and language choices. Yes, I know there are always exceptions. Don’t resort to using .NET classes when a cmdlet will do. Use standard verbs and meaningful nouns in your command names. But perhaps the biggest peeve for me is the continued use of the Return keyword.

Whenever I see the Return keyword, I feel the script author has not fully grasped the PowerShell paradigm. To my way of thinking we don’t return values we write objects to the pipeline. The only time I use Return is when I intentionally want to bail out of a script or function and gracefully terminate everything. Usually when I see the use of Return I also see a lot of unnecessary helper functions each intended to “return” something. This only adds to the (unneccessary) complexity of your work. Add in a lack of documentation and you have a mess of, let’s call it, sub-optimal PowerShell.

A well-crafted PowerShell script file can be a thing of beauty.

The pipeline opens,
objects blossom sending joy
formatted as bliss

What do you think? What have you seen in your company or in the wild that is good, bad or ugly?

What Made the Scripting Games Easier

I can easily say that the quantity and caliber of script submissions in this year’s Scripting Games has been amazing. I congratulate all of you on your hard work and trust it will pay off. I’d say a primary goal is education. Not only will you pick up tips from the judges but also from looking at the other script submissions. Another area that I’m curious about is tools: what did you use primarily to develop or write your PowerShell scripts and functions? There are a number of scripting editors available to you and if you were still using Notepad I hope you’ll follow up on some of these products. Some are free and others have extensive features and corresponding benefits. I’m pretty sure all of the commercial products offer a free download and trial period so I always encourage people to try them all out and find one that meets your needs and budget.

[wpsqt_survey name=”PowerShell Editor”]
Final Results 5/2/2011 8:00AM EST
Here are the final results, which probably won’t surprise too many people.

Results 4/25/2011 8:00AM EST

Here are updated survey results.

Results as of 4/15/2011 11:00AM EST
Still not too many surprises. If you haven’t voted, please do.

If you haven’t voted, please do, but only once. No fair stacking the deck! Thanks for your participation.

Scripting Games 2011 Notes from the Field

I’ve been making headway in reviewing and judging entries in the 2011 Scripting Games. I know there has been a lot of discussion about the lack of comments and I’m doing what I can with entries I judge, but I’m not guaranteeing anything. What I will do is put down some overall comments and impressions that I hope you can use for the remaining events. Continue reading