Recently, I was working out some problems in my script that I’m developing in my Azure environment, and a thought had occurred to me while I was working: Is commenting in my scripts a waste of time?
While I was building my script, I was actually using a lot of Write-Verbose messages so that way I could monitor the commands as they executed by using the -Verbose parameter. This was especially helpful in my If/Else statements, or my Try/Catch statements, so I could monitor what patch my script was heading down to make sure it was doing what it was supposed to do. I also added some extra bits here and there to make sure that my variables were generating as I expected them to. Very quickly I found that I was actually duplicating the work I was putting into commenting my code with my Write-Verbose statements. This is what lead me to my to the thought that perhaps comments aren’t really the way to go.
If you’ve coded a robust function, there should almost never be a time when an admin has to dig into your scripts. This means that the only time someone is ever going to look at it, is when something goes wrong. Instead of tearing through your code and figuring out at what point things fall apart, you could far more quickly and easily execute the script with -Verbose, and see the last command executed before everything hit the fan. After all, if it’s a script that has worked well for a long time, it’s more likely that something changed in your environment more so than the script just breaking for no good reason.
I still use commenting, but more really for my own sanity, such as tracking which curly bracket is closing which statement, and of course when adding my Comment Based Help! But for the most part, I’m seeing less reason to use commenting over Write-Verbose, because of the usability that the latter supplies. I’d actually like to hear what other people think about this. Let me know in the comments below!