Extra Points for Style when writing PowerShell Code

April 13, 2011 at 9:26 PMAndy Schneider

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.

Use Proper Naming conventions for your functions and scripts.

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.

image

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.

image

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.

image

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.

image

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.

image

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.

Summary

  • 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?”

Posted in: PowerShell | Scripting Games 2011 | 2011SG | Coding Style

Tags:

Add comment

  Country flag

biuquote
  • Comment
  • Preview
Loading