Are there well-known PowerShell coding conventions

coding-standardscoding-stylenetpowershell

Are there any well-defined conventions when programming in PowerShell?

For example, in scripts which are to be maintained long-term, do we need to:

  • Use the real cmdlet name or alias?
  • Specify the cmdlet parameter name in full or only partially (dir -Recurse versus dir -r)
  • When specifying string arguments for cmdlets do you enclose them in quotes (New-Object 'System.Int32' versus New-Object System.Int32
  • When writing functions and filters do you specify the types of parameters?
  • Do you write cmdlets in the (official) correct case?
  • For keywords like BEGIN...PROCESS...END do you write them in uppercase only?

It seems that MSDN lack coding conventions document for PowerShell, while such document exist for example for C#.

Best Answer

@Robert Harvey referenced some good formal links. By way of a less formal document, my thoughts would be:

Use the real cmdlet name or alias?

Only use the alias if it is more clear than the full name. For example, I think most people would find dir or ls more clear in a script than Get-ChildItem based on previous experience (e.g. basically anyone writing a PowerShell script has one of those two many times in either DOS batch scripts or Unix scripting).

Specify the cmdlet parameter name in full or only partially (dir -Recurse versus dir -r)

In a script, I would fully spell out the name because (unlike the above example) I cannot think of a time where the shorter switch would actually be more clear than spelling it out. Shorter switch names are to save typing. At a command line, this is imperative. In a script, the extra keystrokes are well worth it for readability and maintainability.

When specifying string arguments for cmdlets do you enclose them in quotes (New-Object 'System.Int32' versus New-Object System.Int32

Enclosing string arguments in quotes seems much more clear when reading through the code, so I would include them.

When writing functions and filters do you specify the types of parameters?

Only when there is a need to do so to resolve ambiguity for the interpreter (which does happen). If you are going to try and put types on everything, you might as well go and write C# command line applications (which isn't always a bad thing, but it negates the time savings you get by scripting).

Do you write cmdlets in the (official) correct case?

You should. I usually do. When hurried I have been known to be a little lax on case since it does not syntactically matter.

For keywords like BEGIN...PROCESS...END do you write them in uppercase only?

No. This is not FORTRAN. I think most people find begin or Begin more readable than BEGIN. There is a reason we associate all caps with shouting online and shouting the most mundane portions of the program hinders readability by drawing one's attention to the parts that matter the least.

The guiding principal should be readability. Scripts, by their very nature as quick and dirty programs, veer towards write-only code. Your every decision should be made to ensure that you and your team can still understand the script in six months. Try to take yourself out of your own shoes when looking at your code and ask this question: "if I had started this job a week ago (and so was not really indoctrinated into the general culture) would I find the way this is written illuminating or confusing?"

Related Topic