Summary: The 2013 Windows PowerShell Scripting Games Competitor’s Guide is posted today.
Microsoft Scripting Guy, Ed Wilson, is here. Don Jones from PowerShell.org is back with us today with the 2013 Scripting Games Competitor’s Guide.
Take it away, Don…
Welcome to the 2013 Scripting Games, now managed by PowerShell.org! This guide is designed to help you understand how the games work and what you can expect.
Important See yesterday’s blog, 2013 Scripting Games Start April 22!, for information about the events, tracks, voting, and prizes.
Register
First up, you’ll need to register for the Games by logging on to http://TheScriptingGames.com. Note that there is no “www” on this URL. When you register, you’ll be asked to select a track. This is a one-time decision, and you may choose from:
- None: You don’t want to compete, but you do want to grade other folks’ work by voting.
- Beginner: You’ll be able to vote on all events, but you will be able to submit only one entry per event in the Beginner track.
- Advanced: You’ll be able to vote on all events, but you will be able to submit only one entry per event in the Advanced track.
Caution We ask that you not include any personally identifiable information in your entries. This includes your name, email address, or other contact information.
Games guidelines
Now, these are just ideas for you to consider. They’re not rules, and our judges won’t universally agree on every one of the ideas. So don’t think of this as a magic checklist that will make you win. You don’t even need to force yourself to do all of these things—but keep them in mind.
- We love to see error handling, especially in the Advanced events. But we don’t like error suppression. That is, if an error occurs, we should see the error, or you should be doing something about it like logging it or displaying an alternate message.
The exception: it’s okay to suppress an error that means “everything is going fine.” For example, you try to delete a file that doesn’t exist, and you get an error message. Well, that’s fine. At the end of the day, the file isn’t there, and that’s what you wanted. If you do choose to handle an error, make sure you’re doing so intelligently. Don’t wrap your entire code in a big Try{} block. Only wrap the commands that you anticipate will have an error, and Catch{} (and handle) that error. - We hate seeing people do more work than is necessary. For example, you shouldn’t ever prompt the user for a missing parameter. Use the Parameter() decorator in Windows PowerShell to mark the parameter as mandatory.
- We love self-documenting scripts. That doesn’t just mean comments, although those are pretty awesome, too—especially comment-based Help. Using stuff like full command names and full parameter names (and no positional parameters) makes a script more self-documenting.
Other examples are less obvious. Here’s one: if you’re accepting input arguments, do so via declared, named parameters, not by using the $args collection. $ComputerName (a named parameter) is a lot more meaningful than $args. - We hate inconsistency. In whatever you write, try to be consistent with what’s already in Windows PowerShell. A parameter named ComputerName is great; a parameter named ComputerNameS is not great. Nothing else in Windows PowerShell uses the plural, so you shouldn’t either.
- We love scripts and commands that output objects and not formatted text. That means you shouldn’t embed a Format cmdlet in your script, nor should you use Write-Host in most cases. Exceptions are made by the name of your script or command; for example, we’d expect a command named Show-Info to show information on the screen, implying Write-Host is being used. A command named Get-Something, on the other hand, should output unformatted objects. We’ll pipe those to a Format command ourselves if we want them formatted.
- We hate scripts that are hard to read. With scripts (as opposed to one-liners), focus on neat formatting. Avoid the backtick (`) as a line continuation trick because that little bugger is hard to see.
- We love elegance. For example, a lot of folks think the expression "$computer cannot be reached" is easier and less complex than ("{0} cannot be reached" –f $computer)—even though these two expressions produce the same result. Both of those are prettier than ($computer + “ cannot be reached”). Just keep that in mind.
- We hate redundancy…well, not in server farms, but definitely in script. For example, is all this really needed: Get-Service | Select-Object –Property @{n='Name';e={$PSItem.Name}}? Could you simply go for Get-Service | Select-Object –Property Name and get the same effect with less typing? We’re not saying this kind of thing will land you on a judges Worst list, but we know it’ll keep you off some judges Best lists.
- We love functions that use [CmdletBinding()] and take advantage of the features it enables. For example, if you’re manually setting something like $VerbosePreference or $DebugPreference at the top of your script, you’re missing the point.
- We hate scripts that pollute the global scope. It’s not yours. We don’t track mud into your house, don’t litter up our global scope with your variables.
Exception: if you write a script module that politely adds global “preference” variables and then politely removes them when we unload it, that’s cool.
Don’t over obsess
In some event scenarios, we’ll give you an example of the expected output. It’s an example, not a mandatory deliverable. Basically, if you have all the right property names and the values look legitimate, you’re fine. They don’t need to be in the order we list them, and they don’t need to exhibit the exact same formatting, unless the event scenario calls out a specific requirement. In many cases, the example output is formatted to fit in a PDF file. It’s going to look different in the Windows PowerShell console, and we’re cool with that.
However, make sure that you meet the scenario requirements. If a requirement says to display a value in gigabytes, you’d better do it. Expect your Crowd Score to be pretty low if you display in bytes when the scenario explicitly asked for gigabytes.
Let’s be clear on something: if your goal going into the Games is to get on every judge’s Best list, you’re playing for the wrong reasons. If your goal is to get an amazing Crowd Score in every event, you’re probably going to be disappointed. This is a learning event.
Here’s another way to think about it: you’re going to have your script reviewed by dozens of peers, and possibly get some expert feedback from some of the biggest names in the industry. That alone is worth participating. The prizes are just icing on the cake!
DO NOT treat the previous list of guidelines as some kind of secret checklist for winning. It isn’t. They’re pretty good ideas in general, but they’re not the only good ideas. Like all rules they come with their own exceptions.
DO obsess about finding a clever, elegant, well-written solution to each problem. Knock our socks off!
Try to not miss the point
Something different about the Games this year: You’ll notice that the only score you’ll receive is from your peers in the community—and we can’t tell them how to score you. Heck, some of them may not feel they’re even qualified to hand out scores, and a few of those might be right (more on that in a moment).
The score is nice—but it isn’t the point of the Games. The point is to think of creative approaches to real-world problems and to implement those approaches the best way you can.
Our expert judges will be picking their Best and Worst lists to highlight creativity, attention to detail, and overall sk1llz. Every judge will have different opinions, preferences, and techniques; and they’re all purely subjective. We’re not giving them any guidelines. So there’s no secret checklist for winning.
Our judges will blog about what they like and don’t like. And that is the real point of the Games: to learn.
Thanks to our presenting sponsors
Generous support from our sponsors makes the Games and all of PowerShell.org possible.
Please offer them your support and thanks.
GOOD LUCK!
~Don
Thank you to Don Jones and to the rest of the Windows PowerShell community for sharing this. Join me tomorrow when we will reveal two practice events for the 2013 Scripting Games.
I invite you to follow me on Twitter and Facebook. If you have any questions, send email to me at scripter@microsoft.com, or post your questions on the Official Scripting Guys Forum. See you tomorrow. Until then, peace.
Ed Wilson, Microsoft Scripting Guy