Don't forget your GETs - The importance of naming consistency

Don't forget your GETs - The importance of naming consistency

  • Comments 4

PowerShell and SMO are getting together like chocolate and peanut butter.  Yesterday I blogged about Bob Beauchemin's TechEd talk about the today and today I see Dan Sullivan's PowerSMO blog entry: http://pluralsight.com/blogs/dan/archive/2006/11/07/41936.aspx .   Dan includes the scripts he used in a ZIP file so you can easily use them.  I really liked what Dan is doing with one exception - his scripts don't use the naming standards.  In particular, his scripts don't use "get".  For example, here is how it gets the SMO constructors:

PS C:\demos> SMO-ctors (SMOT-ManagedComputer)
ManagedComputer()
ManagedComputer(String machineName)
ManagedComputer(String machineName, String userName, String password)
ManagedComputer(String machineName, String userName, String password,
ProviderArchitecture providerArchitecture)
PS C:\demos>

Cool function but where is my GET?  I want to take this example to make 2 points:

  1. The community will get the naming consistency it demands.   We made the conscious decision to not put an naming enforcement mechanism into Windows PowerShell.  That means that we may or may not end up with a consistent set of names.  It is our shared responsibility to point out when the naming guidelines are not being used and to respectfully point this out and ask for change.  We don't need to be butt heads about it but if we don't push for consistency, we won't get it.
  2. I TOTALLY understand why it is tempting to drop your "get"s.  It can seem unnecessary and awkward at times.  The "get" makes sense after you implement the full set of verbs for a noun but you often start with the "get" and by itself, it can sometimes seem awkward. 

So here is the point about "gets" - You should ALWAYS define them but you don't have to use them.  YUP- that's right.   We've anticipated this issue and addressed in our design.  Let me give an example to illustrate.  Let's say that you are about to develop a bunch of scripts manipulating  NumaNumas  (I don't know if there is such a thing as a NumaNuma but I had that silly video on my mind ( http://www.youtube.com/watch?v=60og9gwKh1o ) so I thought I would use it. )  Anyway so the first thing you are going to do is to write a script (or cmdlet) which gets NUMAs and you might be tempted to define it as "NumaNuma" but DON'T  - you are not penalized for following the guidelines. 

PS> Get-Command *numa*
PS>
PS> function Get-NumaNuma {"Numa Numa baby"}
PS>
PS> Get-NumaNuma
Numa Numa baby
PS>
PS> NumaNuma
Numa Numa baby


That's right, the "GET" is optional!  The way our command resolution works is that we take the token you specify and look it up.  If we find it, we use it.  If we don't find it, we stick a "GET-" in front of it and try again.  This means that you can define "Get-Numa" and invoke it with "numa" - the best of both worlds.  

Let me also quickly point out that if you follow the guidelines, it becomes pretty easy to develop a family of very pithy aliases.  Imagine that you have the following commands.

Get-NumaNuma
Set-NumaNuma
Export-NumaNuma
Import-NumaNuma
New-NumaNuma
Clear-NumaNuma
Copy-NumaNuma
Invoke-NumaNuma
Move-NumaNuma
Remove-NumaNuma
Rename-NumaNuma
Stop-NumaNuma
Start-NumaNuma

What you do is to pick a reasonable 2 or 3 letter term for your noun and then leverage our standard aliases for verbs to produce:

 gnn   Get-NumaNuma
 snn   Set-NumaNuma
epnn   Export-NumaNuma
ipnn    Import-NumaNuma
 nnn    New-NumaNuma
clnn    Clear-NumaNuma
 cnn    Copy-NumaNuma
 inn     Invoke-NumaNuma
 mnn   Move-NumaNuma
 rnn     Remove-NumaNuma
rmnn   Rename-NumaNuma
spnn   Stop-NumaNuma
sann   Start-NumaNuma

The benefit is that it is consistent and therefore easy to learn and remember.  If we don't press for consistency, we won't get it and we'll end up in a world that is unpredictable and therefore difficult to learn and remember.  By the way - check this out yourself by running the following commands:

gal g*
gal *al

So Dan, I love your stuff but please don't forget your "get"s. 

Cheers!

Jeffrey Snover [MSFT]
Windows PowerShell/MMC Architect
Visit the Windows PowerShell Team blog at:    http://blogs.msdn.com/PowerShell
Visit the Windows PowerShell ScriptCenter at:  http://www.microsoft.com/technet/scriptcenter/hubs/msh.mspx

Leave a Comment
  • Please add 1 and 6 and type the answer here:
  • Post
  • You talk about naming conventions for PowerShell, but are there are written guidelines and practices?  If there are, you should point people to them.

  • By popular demand the "Get-" convention is being used for the SMO and SMOT commands.

    The names in the article may not have been changed by the time you read this, so keep this in mind so keep this in mind when you read it.

    The download for the script file includes both the old "bad" naming conventions (.ps1.old) and the "good" naming conventions (the .ps1 file)

    For example:

    SMO-Server

    is now

    Get-SMO_Server

    and

    SMOT-Server

    is now

    Get-SMOT_Server

    To save on  typing now all of the commands have shorted aliases.

    gs_Server for Get-SMO_Server

    and

    gst_Server for Get-SMOT_Server

  • > By popular demand the "Get-" convention is being used for the SMO and SMOT commands.

    I'm renewing my membership in the Dan Sullivan fan club!!  :-)

    Thanks Dan - that is super.

    Jeffrey Snover [MSFT]

    Windows PowerShell/MMC Architect

    Visit the Windows PowerShell Team blog at:    http://blogs.msdn.com/PowerShell

    Visit the Windows PowerShell ScriptCenter at:  http://www.microsoft.com/technet/scriptcenter/hubs/msh.mspx

  • rnn ->    Remove-NumaNuma

    rmnn ->  Rename-NumaNuma

    I think those are the wrong way around - unless you just want to be perversely un-UNIX.

Page 1 of 1 (4 items)