Simple Script Template with Built-in Help for PowerShell

I’m always looking to improve my code while also keeping things as simple as possible. One thing that I find ever so annoying is having to figure out what a script does and determine if I can run it safely without some unwanted, irreversible side-effects. To that end, here’s a very simple script template that features two built-in levels of help.

Two parameters are provided in the template and you would of course want to add any additional parameters as needed.

-Help will produce exactly what a user would expect: information that identifies the script and its usage

-History is sort of an extended help with maintenance notes appended.

Use of either parameter will result in the display of information about the script and nothing more. Users of your scripts will always know that they can safely run your scripts with the -Help parameter to find out what it does and how to use it. Since -Help (or -History) will always cause the script to terminate early, there are no concerns about messing anything up.

One note, it is vitally important that the verbiage in your help information is accurate and makes sense. Obviously no one will find the built-in help very useful if it just contains what I’m providing in this template.

Not too much more to say about it as the script is fairly self explanatory.

Here it is:

Param ([switch]$Help,[switch]$History)
$HelpText = @'
#######################################################################################
 Name    : Template.ps1
 Date    : 03/04/2011
 Author  : xb90@PoshTips.com
 Purpose : Describe the purpose here
 
 Usage   :
           ./template [-Help][-History]
 
            where
                  -Help      produces help output
                  -History   produces help output with maintenance history
 
 Notes   : Include any additional notes here if needed (otherwise delete this section)
 
#######################################################################################
'@
$HistoryText = @'
 Maintenance Log
 Date       By   Updates (insert newest updates at top)
 ---------- ---- ---------------------------------------------------------------------
 03/04/2011 xb90 New Script
#######################################################################################
'@
 
if ($help -or $History){
	$HelpText;
	if ($History){$HistoryText}
	exit
	}
 
##
## Main Script
##
 
function FancyDisplay{
    param ([string]$txt,[int]$len)
 
    write-host $txt.padright($len) -back cyan -fore blaCK
    }
 
FancyDisplay "" 40
FancyDisplay " PowerShell Script Template" 40
FancyDisplay "         Courtesy of PoshTips.com" 40
FancyDisplay "" 40