Comments

PowerShell code tells you how, but the PowerShell comments tell you why. Here are the ways to comment your PowerShell and some accompanying best practices.

Mystery code

Here is a scenario all too familar: You are heads down, writing an awesome script. Since you are writing it you know exactly how it works and why you made the design decisions you did. You are so clever! The code is so obvious that it pretty much explains itself to someone reading it.

Now here’s how reality usually goes: A peer needs to make a change to your script. They wonder what the variable name $m represents. They try to trace flow of your script, constantly having to scan to find the function definition you created. Why did you create a special function for that? Couldn’t that be done with the <insert applicable cmdlet name here> cmdlet? What are the prerequisites for this code to run? Does it require a minimum version level of PowerShell? And the questions go on and on.

Even if you as the author come back to review it months down the road, can you reliably remember the logic you used to design and write it?