What To Do / Not To Do in PowerShell: Part 6

It's extremely common for programmers and scripters to use comments in their scripts. Inline comments help to explain what the script is doing, and provides a clue to whoever comes in later down the line as to what the author was thinking.

I say, "Stop using them."

Yes, you read correctly: Stop using inline comments. Why? Well, because the only benefit someone reading the code. Why not provide that same kind of documentation in a way that also benefits the person using the code?

To that end, I suggest using Write-Verbose and Write-Debug for your comments. I tend to use Verbose for things I don't mind the end-user seeing, such as progress information and status updates on the script's execution. Debug is more internal-only stuff, like the contents of variables and little reminders. Either form of output can be turned on by simply adding "-verbose" or "-debug" when running the script. Omit those switches, and there's no output from those two commands.

Okay, okay, you'll probably still have a use for plain old comments. But try to get into the habit of putting some documentation into Write-Verbose and Write-Debug, where those "comments" can take on a wider role.