Summary: Ed Wilson reveals the top ten suggestions for scripters at the end of week one of the Windows PowerShell 2011 Scripting Games.
Microsoft Scripting Guy, Ed Wilson, here. You still have time to submit entries for events 1 – 5. The deadline for event 1 is Monday at 12:01 AM (Pacific Time (-8 GMT). After spending a week looking at several hundred beginner and advanced scripts, I decided to list my top ten suggestions. These suggestions are not directly related to the top ten mistakes—they are just suggestions. I am not listing them in any order of importance.
1. Make sure that you know how to use the Get-Help, Get-Member, and Get-Command cmdlets. These three cmdlets are the bread and butter, the peanut butter and jelly, the chocolate and macadamia nuts of Windows PowerShell cmdlets. I do not mean just simply know about them, I mean really know how to use these three cmdlets for all they are worth. Jeffery Hicks tweeted some really great advice when he recommended that you look up a cmdlet in help before using it and that you examine all the information about the cmdlet, including the examples. You should do this, he said, even if you “know” how to use the cmdlet. I can vouch for this advice. For some of the events, I deliberately sought out obscure switches and parameters—capabilities that, if found, would make for a simple, elegant, and easy answer to the problem.
2. If Windows PowerShell has an intrinsic capability to perform a task, you should use that capability and not pull in some other technology such as COM or WMI for no reason. If you have a specific reason (such as performance or backward capability) that dictates such an approach, that is fine, but you should first investigate what Windows PowerShell has to offer.
3. Functions should return objects.
4. You should use the Windows PowerShell native capabilities to produce output (such as Format-Table, Format-List, and Format-Wide) and not waste time manually creating and formatting output unless you have very clear and specific design goals.
5. Make sure that you test your script prior to release. If you are using the Windows PowerShell ISE, you should also test it in the Windows PowerShell console (and vice versa). If you uncover a dependency that keeps it from running in one environment or the other, correct the dependency or make the appropriate checks to notify the user what is happening. If you are using the Windows PowerShell ISE to do your development, realize that there are three different panes, and that changes to one does not always effect a permanent change to your script. The best way to check your script is to close the Windows PowerShell ISE, and then open it up with a fresh environment to see if the script still works.
6. Always back up your work prior to making massive changes to your script.
7. If your script is hard for you to read, how do you think it will be for someone else? Make sure that you can read and understand your code. If not, then organize it in such a way that it is easier to read.
8. Consider using the Set-StrictMode cmdlet to prevent reference to initialized variables, non-existent properties, variables without names, and calling a function in the manner of a method. The use of this cmdlet can help enforce best practices, and therefore simplify troubleshooting later down the pike.
9. Use functions to promote code reuse, to encapsulate logic, and to simplify function design. I prefer functions that have a single way in and a single way out. In addition, I prefer multiple simple functions to a single multipurpose monolithic function. I find simple to be easier to read and to understand.
10. If you use a non-standard cmdlet, module, or snap-in early in your script, you should test for that dependency and notify the user that the dependency does not exist (if that is the case) and gracefully exit. You can also offer to install the dependency for the user and do so for an even better user experience. You should not, of course, install stuff without the user’s permission or knowledge.
Ed Wilson, Microsoft Scripting Guy