Naming Conventions
In general, prefer the use of full explicit names for commands and parameters rather than aliases or short forms. There are tools like PSScriptAnalyzer's Invoke-Formatter
and scripts like Expand-Alias for fixing many, but not all of these issues.
Use the full name of each command.
Every PowerShell scripter learns the actual command names, but different people learn and use different aliases (e.g.: ls for Linux users, dir for DOS users, gci ...). In your shared scripts you should use the more universally known full command name. As a bonus, sites like GitHub will highlight commands properly when you use the full Verb-Noun name:
Use full parameter names.
Because there are so many commands in PowerShell, it's impossible for every scripter to know every command. Therefore it's useful to be explicit about your parameter names for the sake of readers who may be unfamiliar with the command you're using. This will also help you avoid bugs if a future change to the command alters the parameter sets.
Use full, explicit paths when possible.
When writing scripts, it is only safe to use ..
or .
in a path if you have previously set the location explicitly (within the current function or script). Even if you have explictly set the path, you must beware of using relative paths when calling .NET methods or legacy/native applications, because they will use [Environment]::CurrentDirectory
which is not automatically updated to PowerShell's present working directory ($PWD
).
Because troubleshooting these types of errors is tedious (and they are easy to over-look), it's best to avoid using relative paths altogether, and instead, base your paths off of $PSScriptRoot (the folder your script is in) when necessary.
Avoid the use of ~
to represent the home folder.
~
to represent the home folder.The meaning of ~ is unfortunately dependent on the "current" provider at the time of execution. This isn't really a style issue, but it's an important rule for code you intend to share anyway. Instead, use ${Env:UserProfile}
or (Get-PSProvider -PSProvider FileSystem).Home
.
See also the Capitalization Conventions
In the Code Layout and Formatting chapter, there is a section on capitalization conventions.
Last updated