The Surly Admin

Usings Verbs and Nouns

There are a lot of Administrators writing Powershell scripts out there.  A lot!  And more people dip their toes into the waters every year, including yours truly.  Did you know that Powershell even has best practices on naming your scripts?  Here are my thoughts on it.

A Little History

So back in the ancient days of vbScript–you know, last year–we didn’t have a lot of standards in the language.  You could pretty much call a variable anything you wanted and vbScript was perfectly fine with it.  But over many years of usage certain standards began to emerge because trying to reverse engineer a script is hard enough, but trying to do it while keeping all of the variables–and their content type–in your head made it much harder.  Strings started with str, Objects with obj or o and several others.

Naming the script, however, was the wild west and I’ll be the first to admit I struggle with this on my old scripts all the time.  The problem is essentially what made sense to you 2 years ago may not make any sense now and I’m horrible at remembering what I named things, so invariably I end up scanning through all my script folders until I find something that sounds right and then going into it and looking.  I found myself doing the same thing with Powershell, and it was more than a little frustrating.

Standardization to the Rescue

Turns out Microsoft has set aside rules for naming your scripts and custom cmdlets!  You can read about it here in brutal detail: Approved Verbs for Windows Powershell Commands.  But the core of it is, use the same verbs that the built-in commands use and suddenly things start making a lot more sense.  Have a function that retrieves all of your OU’s and want to pick one and save it in your clipboard?  Get-OULDAP.   Honestly have to come up with a better noun there.

One verb I would like to see added is Report.  A lot of my scripts are reports, and I see the Get verb as more of an object retrieval verb.  What I mean is the output from a Get cmdlet will give you an object that you can manipulate if you want to.  Report would be a cool verb in that it tells you the output is going to be a very specific, formatted entity.  Who knows, maybe if I talk about it for enough years we’ll see it happen!  Or not.

Since I started using Get, Report, Remove, etc finding my scripts has become much easier because I can narrow down my search just by the name.

Nouns – do it your way

The funny thing about a lot of IT Administrators is that as much as we love and push for standardization, we tend to resist them in our own life.  Loudly.  And here’s where you can get the best of both worlds.  Use a standard Verb, add a dash, then call the script anything you want.  I will recommend staying away from spaces though as referring to things with spaces in them in a Windows world is still a royal pain, so just save yourself the pain and don’t use them.

No kidding, I honestly have a script called Report-NewUsersAndEmail-WithHTMLandNoAuth.PS1.

Of course, having written this now I’m going to have to invest the time and go through my Powershell scripts folder and rename all my scripts to the standard.  File that under “Practice what you preach”.  That’s why they invented weekends, right?

January 17, 2013 - Posted by Martin9700 | Powershell - Best Practices | Powershell Nouns, Powershell Verb Add Report, Powershell Verbs