Take the 2-minute tour ×
Programmers Stack Exchange is a question and answer site for professional programmers interested in conceptual questions about software development. It's 100% free, no registration required.

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#.

share|improve this question

2 Answers 2

@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?"

share|improve this answer

Microsoft has written and published a very good set of Cmdlet Development Guidelines

Excerpt:

The topics in this section provide development guidelines that you can use to produce well-formed cmdlets. By leveraging the common functionality provided by the Windows PowerShell runtime and by following these guidelines, you can develop robust cmdlets with minimal effort and provide the user with a consistent experience. Additionally, you will reduce the test burden because common functionality does not require retesting.

In This Section

These guidelines are not limited to any language (they do not mention a language), and are perfectly applicable when writing Cmdlets in PowerShell.

Using these guidelines will help you write clear, discoverable, usable and reuseable Cmdlets. I find after creating several PowerShell modules following these guidelines is not hard, and helped me become a better PowerShell developer. That skill is directly usable when writing simple scripts as well.

share|improve this answer
1  
These seem more about how to write cmdlets, rather than how to write PowerShell. –  Philip Kendall Jan 25 at 23:41
    
@PhilipKendall they do indeed. This may not answer the complete question, but i do belief this adds value to the question. Note that you can write your Cmdlets perfectly in pure PowerShell, and that these guidelines really help with that as well. If you can write a good Cmdlet in PowerShell, than you can write good PowerShell scripts as well. –  oɔɯǝɹ Jan 25 at 23:44

Your Answer

 
discard

By posting your answer, you agree to the privacy policy and terms of service.

Not the answer you're looking for? Browse other questions tagged or ask your own question.