This is a blog post I have been meaning to write for a while. Really, being a judge for the 2011 Scripting Games caused me to get this post out. As a judge for the games, I have been reading dozens of scripts every day, and I am sure you can imagine it can get a little tiresome reading through code. That being said, I am learning a ton and have thoroughly enjoyed seeing some great scripts and very innovative solutions. This post is both a commentary on what I have seen in the Scripting Games and my opinions on some best practices.
Don’t make Scripts more complicated than they need to be
Use Cmdlets when possible. Only resort to invoking .NET code when there is no cmdlet available.
Learn to use the pipeline. This can be extremely efficient. In order to do this well, your functions need to be pipeline friendly. Learn to use “AcceptVaueFromPipeline” in parameters, but don’t overuse it.
There is a clearly defined list of acceptable verbs and also strong guidance on how to name your nouns. Also, run Get-Verb to see all the available verbs that you can use. For nouns, if you need to disambiguate from another set of Cmdlets or functions, use a 2 or 3 letter prefix. Also, always use Singular nouns. Plural nouns get complicated. For example,the noun child is used quite often in providers. Pluralizing “child” turns it into “children” which is not very discoverable, especially if you consider localization.
Use variables that make it easy to understand what you are doing in your script. Comments in code are great, but your code should be readable and understood without them. In general, I would choose good variable names and clear processes over heavily commented code. Comment based help is completely different. It’s great. Use it. Include a lot of examples in your comment based help.
Comment Based Help
Comment Based Help is great. However, it can be very verbose in your script. In the games, I have seen people squeeze it all together and make it hard to read. I would say the most important points in help are the examples. In your examples, start at the easiest way to use your script and add more complexity in more examples.
Parameters and Advanced Functions
There is a ton of great functionality in Advanced Functions. In particular, with just a bit of annotation, you can get a lot for free when it comes to parameters. You can force a parameter to be mandatory. You can say whether or not it can take values from the pipeline. You can run a number of validation against them, and the list goes on. However, with all these options, and if you have 3 or more parameters, it can get pretty verbose pretty quick. Here's how I handle the verbosity. Always put spaces between parameters.
Using Tabs and Curly Braces
In the ISE and most script editors, a TAB is equal to 4 empty spaces. I think this is a good number and is pleasing to the eye when reading code. You should use Tabs and Curly Braces to visually show where a block of code begins and ends.
Along these lines, I would also like to point out when I use blank lines in code. Sometimes in a function or some block of code, I may be doing two or three sets of operations. If you have much more than that, I would suggest you need to break down your function, but that is a whole other blog post.
In this example, I have added blank lines between chunks of code that seem like they should be grouped together.
Looking at this code I wrote 2 years ago, I probably should have broken these down into more usable code and wrote some functions like New-NaElement and New-OutputObject. Oh well, looking back and reflecting is a good thing. I now know better. Also, naming variables was kind of weak here as well. $NaElement and $NaElement2 is bad. I should have named them $lunInfoElement and $occupiedSizeElement or something along those lines.
- Write the simplest code possible, but not too simple that you lose functionality
- Let the code document itself
- Make it pleasing to the eye and easy to follow visually – Think of it as art
- Ask yourself “If I was reading this for the first time, would I understand how it work?”