Documenting Scripts

It's worth your time to spend a few minutes documenting your scripts. You can do it while you're creating the scripts or spend a couple of minutes when you've finished, but in either case it'll save you some headaches later. Documentation is done by adding comment lines, which start with a # character in PowerShell (or by using REM, short for remarks, in batch files).

When you write a good script, it'll automate a job for you, and you may not have to touch it again for six months. I don't know about you, but if I haven't touched something in six months, I just don't remember it as well. However, by adding a few lines here and there.

Documentation in scripts starts with a few lines at the beginning that could be like this:

#Script written Sep 2009 by Mike Gibson
#Purpose. Checks status of service.
#Expects Display Name of service
# as a parameter ($Name)

Notes can also be embedded within the script. This is often done when the script includes large blocks of code. These notes are easy to add while you're writing and debugging the script and don't need to be complex.