Summary: Ed Wilson reveals the top ten mistakes that are made during week one of the Windows PowerShell 2011 Scripting Games.
Microsoft Scripting Guy, Ed Wilson, here. It has been a really fun week, and I have completely enjoyed grading the entries that have been submitted to the 2011 Scripting Games this week. It is not too late to join in the fun. 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). Even if you miss a deadline, that is no reason to not enter and submit a script for the next event. Where else can you get some of the world’s best scripting experts to review your script and provide comments—for free!
Keep in mind that the purpose of the 2011 Windows PowerShell Scripting Games is to teach scripting techniques. The scenarios are realistic, the tasks are common, and the judging criteria incorporate best practices. You should therefore be interested in the 2011 Scripting Games even if you are not participating. You should be reading the expert commentators, reviewing the scripts (beginning on Monday) and perusing the Study Guide even if you have no desire to win a free pass to TechEd in Atlanta.
Here are some mistakes that I noticed while grading scripts this week:
1. If a script requires elevated rights to run, your script should check for those rights.
2. Your script should not contain bogus default values, such that when you run the script, it immediately generates an error.
3. A script that is going to be reused should not include hard-coded values. Instead, it should use parameters to allow for maximum flexibility.
4. If you have a parameter that must be supplied, make it a mandatory parameter rather than simply throwing an error if it is missing.
5. If you have a script that has multiple parameters, use comment-based Help tags to provide Help to the user who needs to use the script.
6. If you use comment-based Help, include at least one example of proper usage for each of the parameters and for each of the parameter sets that the script supports.
7. When you arrange your examples for comment-based Help, proceed from the simple to the more complex. If your script supports piping, include an example of that as well.
8. If your script can easily cause an error (for example, getting a process that does not exist) you should provide an appropriate level of error handling, or design your script in such a way as to prevent the error from occurring. One way of designing around this problem is to limit the values that can be supplied to the parameter. A way to handle the error is to use Try/Catch.
9. Of course, your script should work properly, and meet the design requirements. One way to do this is to start with a simple bit of working code and gradually add to it to flesh out the additional features of the script. Do not simply sit down, type 200 lines of code, and expect it to work properly the first time. It is easier to debug 1 line of code than 200 lines of code.
10. You may consider having the script run and perform a basic task. This provides the users with the ability to accomplish a basic task with no additional work. Use switches and parameters to expose additional capabilities. You can group different sets of capabilities by using parameter sets to simplify the command-line scenario.
Ed Wilson, Microsoft Scripting Guy