Weekend Scripter: What to Include in a PowerShell Comment Block


Summary: Microsoft Scripting Guy, Ed Wilson, talks about what to include in a Windows PowerShell comment block.

Microsoft Scripting Guy, Ed Wilson, is here. Something that tends to confuse new scripters, regardless of the language, is what to include in a comment block at the beginning of a script. I have reviewed thousands of scripts for various scripters, and I have seen lots of variation. This variation ranges from nothing at all, no comments, not a thing to nearly complete books that describe everything a script should do, might do, and even ways to improve the script should it come time for revision.

In reality, your script is, well, your script. How you choose to add a comment block at the beginning of your script is, of course, your business. However, I have found a few things that I think should be in the script header comment block:

  1. The name of the script.
    Believe it or not, this is often left off a script. The reason, it seems, is that the file name of the script is the same as the name of the script, and therefore it is redundant information. OK. I can buy that. But at the same time, I like having the name of the script there. It makes it easier for me to identify the script when I am bouncing around between tabs—especially if the name is long. When the name is long, it has a tendency to become truncated on the tab.
  2. The author of the script.
    This may seem like a no-brainer, but apparently, it is not. In fact, I have seen many scripts written where no one wants to claim authorship. It is not that the script is a bad script. Rather, they do not want to support the script. It does not matter if you say the script is not supported, people will hunt you down and ask for changes, complain that it does not work in their Windows NT 3.51 environment, or that it blew up their computer’s mail implementation.
    I get it…really I do. But when talking about what should be in a script block, clearly the person who wrote the script should include their name. This is really important in a corporate environment, but that is also where I seem to run across the desire to remain anonymous the most. The saying is, “Sure, I have time to write the script, I just do not have time to support it.”
  3. Author contact information.
    Of course, if you post to the Internet, you REALLY do not want to include your real email address. But at work, including your email address, and even phone number, is a good idea. It simplifies communication. Of course, this also works in conjunction with item #2.
  4. Version of the script.
    I like including a version number. This is especially true when it comes to supporting scripts. If a person says, “The script blew up,” but provides no version information, it is not all that helpful. But if they say, “I have version 1.2 and it blew up,” you can then reply, “Well, you need version 2.0 because I fixed that bug.” Assuming that there really is a version 2.0 and that you really did fix the bug.
  5. Where you got the idea.
    If you have a script that is based on a script that you found (for example, on my blog), it is a good idea to include the link to that script. Sure, it is nice to give credit, but from a practical standpoint, it is also a good idea because you will have reference information. On my blog, I include extensive discussion about the script, so information about where I got the code would also include a link to reference information about the script. On the other hand, you may have a link to a site that has lots of other scripts, and you do not want to lose that reference.

Now for things that are nice to have:

  1. The version of Windows PowerShell required.
    It is a good idea to include the version of Windows PowerShell. Of course, you can add a #Requires statement at the top of your script, but having it in the comment block is also a good idea.
  2. If elevation permissions are required.
    You can add a #Requires statement that indications if elevation is required, but this is a good thing to add to the comment block.
  3. If specific modules are required.
    Same as the comments for items #1 and #2.
  4. Comments about new types of constructions.
    If you came up with a brilliant idea that you have never used before, it is a good idea to document what you are doing and why.
  5. Comments about specific cmdlets.
    Same as the previous comment.
  6. Ideas for future improvement of the script.
    If you would like to add additional things to the script, but you did not have time when you were writing it, it makes sense to add a ToDo: section.
  7. If there are known errors.
    Most of the time the script may work fine, but occasionally, a script will blow up. If this is a known issue, document it. Of course, you should handle the error, but who knows…

I invite you to follow me on Twitter and Facebook. If you have any questions, send email to me at scripter@microsoft.com, or post your questions on the Official Scripting Guys Forum. See you tomorrow. Until then, peace.

Ed Wilson, Microsoft Scripting Guy 

Comments (3)

  1. Doug W says:

    I was wondering if you could provide a screenshot and code snippet of an example ?

  2. Ken B says:

    I like to include a "usage" function that outlines what the script does, what parameters it expects, basic usage, why it was written, etc.

    That way, when checking for input arguments – if they are missing – just call the ‘usage’ function – it shows that info and exits. It is kind of self-documenting. I’ve been doing it this way since I started writing complex ‘batch’ scripts (running from 2KB
    to 20KB in size using a similar ‘:usage’ block if the expected arguments were missing – just "goto usage")

    An example of what I mean (please, no flames…I’m not an expert in powershell at all! And yes, I try to version my script by the name of the script – this is the second "pre production" version; "production" version start a version 1)

    Having this at the top of the script means less redundant documentation and allows me to reuse lots of scripts

    c:type .do-pst-import-v0b.ps1
    #
    # author: Ken B
    #
    # see usage for details about what this script does
    #

    $inputfile=$args[0]
    #$outfile=$args[1] #not used in this script
    $statusflag=$args[1]

    $debug=0
    $status=0 # set from $statusflag value

    $CRLF="`n"

    $baditemlimit=9

    $errorPreference=’Continue’

    Function Usage
    {
    write-host "Usage: scriptname Inputfile [-status]"
    write-host $CRLF
    write-host "where scriptname is the name of this powershell script"
    write-host $CRLF
    write-host " Inputfile is a CSV file containing the mapping file to import data to the mailbox"
    write-host " the file must contain the following data elements"
    write-host " (aka column headers) to be processed correctly"
    write-host " psmtp,pstfile"
    write-host " note: other column headers are valid, just not used"
    write-host $CRLF
    write-host " the PST data in the PSTFILE will be imported into the mailbox"
    write-host " where the primary smtp address is psmtp."
    write-host $CRLF
    write-host " The primary cmdlets used are:"
    write-host " import-mailbox -id PSMTP -pstfolderpath PSTFILE -baditemlimit $
    baditemlimit"
    write-host $CRLF
    write-host " so kfbrown@gapac.com is valid for the psmtp email address"
    write-host " -status is an optional flag that will show status of processing each object"
    write-host $CRLF
    write-host $CRLF
    write-host " this script was created for MAD activities."
    write-host $CRLF
    exit (1)
    }

    #### end of snippet

    Then, I’ll just call the usage function thusly (and yes, the exit 1 here is probably not needed)

    if ([String]::IsNullOrEmpty($inputfile)) {
    Usage
    exit (1)
    }

    if ($inputfile.contains("-?") -or $inputfile.contains("-h") ) {
    Usage
    exit (1)
    }

    if( !(test-path $inputfile) ) {
    write-host "input file ""$inputfile"" is missing – cannot continue"
    exit (1)
    }

  3. Thanks Ed for posting this. I often wondered what to include in the scripts. Good job.

Skip to main content