Powershell naming convention

Recently I posted about “smart” function names I am using – and we had great discussion about it :) I promised I will write some follow up afterwards and here it comes :)

First of all, I would like to say that I BREAK naming convention of PowerShell and I am fully aware of it, however in my situation positives are outweighs negatives. Because number of people that are not following naming convention is growing, I think there is chance there are some small gaps in PS design that leads to this situation.

First let’s discuss what is naming convention for PowerShell functions:

<Verb>-<Noun>

Good and simple example is New-Object. However what if you need to be more specific? For example what if you want to create new object in SCCM?

Then official way to do so would be New-SCCMObject.

According to official naming convention, retrieving all SCCM related functions can be achieved by calling Dir Function:*-SCCM*.

You can find Microsoft document about PowerShell naming convention here and I highly recommend reading it.

You shouldn’t change verb, only noun.

 

At least based on my experiences, new comers to PowerShell have problems to understand this – most time I saw first scripts from someone, they almost always started with SCCM-* (or any other technology-based prefix). Maybe it’s caused by fact that flexibility to noun is not stressed enough, I think it is caused by missing element of naming convention – ability to specify script category or technology.

Most time I heard some complains about any changes to naming conventions, arguments were that I am breaking existing naming convention. It is true – however that doesn’t say anything about fact that maybe current naming convention should be tweaked little bit to be more flexible – at least due to fact that popularity of PowerShell is growing and especially with modules from Posh V2 exchangeability of PowerShell will be even improved.

My personal feeling is that once someone will decide that existing naming convention doesn’t fit his requirements (for any reason), field is completely opened for him and he can do whatever he wants. Most of the time result is technology-based prefix, however sometimes we can see absurdities like the ones from Citrix ;)

Another common argument is that administrators will have problems with accepting longer function names – but that’s why we have aliases ;)

Another reason why I don’t like always current naming conventions is automation – there is no delimiter between script category and script itself (noun + any extension is single element). To give you example – I am currently using <NameSpace>:<Verb>-<Noun> syntax. If there will be someone that doesn’t like it and would like to switch to default <Verb>-<Noun> syntax, he can use simple function that will just do <Verb>-<NameSpace><Noun> – for example “translate” function Citrix:Get-Farm to Get-CitrixFarm. This is possible due to fact that there is delimiter between namespace (I know it is NOT a namespace, but I like to use that name ;)) and rest of function name. It won’t work other way around – there is no chance how to detect that “Citrix” in “CitrixFarm” is category. Another example is Dmitry’s post called “We need namespaces!” – IF there would be clear delimiter between namespace and function name, you could easily write “using” function yourself - either using same example as Dmitry provides or even better, using script block:

Use-NameSpace –NameSpace Quest.ActiveRoles.ADManagement –Process {

Get-User “Dmitry Sotnikov” | Set-User –city “St. Petersburg”

}

You don’t need to extend PowerShell itself to support this – just write few simple functions and apply consistent naming convention.

 

What I am missing is some industry standard – which delimiter should be used? Should it be “:” as I do, should it be “\” as Dmitry suggests or should it be “::” as in Kirk’s example? I don’t really mind – as long as there is something that everyone will follow, I would be more than happy to change my scripts according to this standard.

 

There are few reasons why I like to use category prefixes:

• It’s easier to understand for both administrators and developers. For developer, category prefix = namespace. For administrator, category prefix = toolbox. So Citrix:Get-Farm can be translated as “Use Get-Farm function from Citrix: toolbox”. If there is any reader that used my naming conventions, please share your experiences.
• Such function names supports further automation – see above examples (translating to regular Posh naming convention, implementing “using” functionality etc etc…).
• It is easier for vendors to introduce functions\cmdlets. Common example is virtualization field – once first vendor will use Get-VM as cmdlet name, rest of them needs to workaround it somehow. Releasing cmdlets\functions and sharing scripts would be much simpler if there would be support for namespaces.
• In my situation, I prefer decentralized development. Many people are writing scripts for single framework and I don’t want to control what they are doing and how they name their functions – now all I need to do is assign prefix to them (you work on SCCM, so you will use SCCM: prefix, someone else works on Altiris, so he will get Altiris: prefix). That way management of bigger projects\frameworks is much easier.
• Using consistent function names – I know it sounds strange, but for example I  have function that will write to event log as part of my framework. What is logical name? Write-EventLog. However that is already reserved by PowerShell itself – so I just specify S4M as prefix (that’s name of my framework), so function name will be S4M:Write-EventLog.

 

Even Jeffrey agrees that this is important to solve somehow. What I am missing at this moment is some kind of naming conventions reservation – I don’t mind how long it will take Microsoft to implement it, however I would like to know how it will looks like, so I could already implement same naming scheme (before it will be too late). There was recent blog post about reservation of keywords – and that’s what I would like to get. Many years ago I started calling my cmd scripts using powershell Verb-Noun syntax, just to get people I worked with used to that logic. Now I would like to do the same – start implementing technologies that will come in future already and prepare people for them.

If you get my point, I highly recommend you vote for Connect feature request We need namespaces from Dmitry Sotnikov.

UPDATE: Read follow up here