itpassionate

Introduction

I don’t know for you, but the following situation happened to me many times.

You work in a team where you exchange scripts. You write scripts for others or you receive scripts that you need to re-use as they did the job they were supposed to do. Sometimes, you need to update a script but the author is no more working in the company and so on…

It could be painful especially if you or another created functions in it, if you don’t understand why specific regions of the the code have been written in a certain way instead of a more functional way. As I’ve written in another post of this blog, the beauty of PowerShell is that you can achieve the same goal in dozen of ways. All are good but depend of the context when you wrote the script.
By the way, you don’t need to have a script 500 lines with functions in it, to not understand all aspects of a script. It could become a problem especially as we are talking of automation.

So, the best way to help yourself (it works also in that way. I promise 😉 ) and help others to understand your script is to create a help section in it.

How? WTFM (Write The Fu*** Manual)

Let’s start the fun part, as you have now the context of the post 🙂

Phase 1: Comments

With PowerShell, you have the option to comment your commands in a script which permits to give the user an idea of what does a specific command.

# the following command will permit you to retreive the last 50 errors in System EventLog of the machine
Get-EventLog -LogName system -EntryType Error -Newest 50

For the newcomers, the syntaxt for inserting a comment in the code is to start a line with the hashtag symbol (#) (My prefered method for an easier reading). As an alternative, you can insert (#) at the end of a command as shown here under.

Get-EventLog -LogName system -EntryType Error -Newest 50 #command to retreive Last 50 System's event

A comment means that Powershell will never try to process the text behind (#).

These comments are good to help you remember specific points of your script or to help others to understand how you wrote your script but it’s limited:

• You need to read the script via an Script Editor (Notepad++, Visual Studio Code, PowerShell ISE)
• If you have a long script or a lot of points to mention, it could reduce the readability of a script
• Difficult to reference everything
• Complicated to give more context on how the script was built

PowerShell conceptors have thought about how to go to the next step and remove those limitations!

How?

Let’s talk about: Comment-based help

Phase 2: Comment-based Help

Here it is 🙂 !! Let’s WTFM

Sometimes, it helps you also when guys that running your scripts are coming back to you after a while and trying to improve the script. (It happened to me several times! 🙂 ). You don’t necessarilly remember everything about the decisions that motivate you to write the script in a specific way.
That’s why I try, as often as I can, to create a “Comment-based Help” section

Indeed, the concept behind “Comment-based Help” is to create a comment block in PowerShell script where you detail everything you need to render the script (especially the way you wrote), totally understandable by anyone who use it. The beauty behind this is that it can be interpreted by PowerShell Help system and render it totally readable outside a script editor context.

Architecture

To be understood and interpreted by the Help system of PowerShell, you need to respect a specfic architecture inside this section. To help you undertand what I mean, here is an example of an empty “comment based help” section:

Delimiters

The “comment-based help” is a section in your script. As it’s a section, it has delimiters that are represented as here under:

Opening the section: <#
Closing the section: #>

This section can be placed at the beginning or at the end of the script. No matters!

Keywords

As mentionned in the picture above, keywords are the key components of your help section if you want PowerShell help to treat it correctly. Those keywords are limited to a specific list as detailed here under:

.SYNOPSIS
.DESCRIPTION
.PARAMETER
.EXAMPLE
.INPUTS
.OUTPUTS
.NOTES
.LINK
.COMPONENT
.ROLE
.FUNCTIONALITY
.FORWARDHELPTARGETNAME
.FORWARDHELPCATEGORY
.REMOTEHELPRUNSPACE
.EXTERNALHELP

To get a better understanding of all those keywords and how to use them, I strongly advise you to read Microsoft Help via the following link:
Microsft Online Help

As additional information regarding keywords, you need to know the following characteristics about them:

• They are not case sensitive
• The order you place them in the “comment-based help” section is not important
• You don’t need all. It will be dependent of your script content

Now, you should have a better understanding on how to create help section in your scripts 🙂
The next step is to validate the functionality via a demo! 🙂

Demo time!

As I’m a VM admin, I’ve wrote a script and it’s located on my local machine. Before sending this script to my colleagues, I would like to check if my help section is working as it should.

1. I Open a Powershell session on machine and navigate to the directory where the script is stored

2. I run the following command to display the help of the script

Get-help .\xVcenter_vMotion_V1_0.ps1

3. PowerShell returns me the help section I’ve created in my script – Taaa-Daaa!!! 🙂

Get-help .\xVcenter_vMotion_V1_0.ps1 -ShowWindow

The result should give the following output:

The big advantages I see having the help in a seperate window are:

• We have the option to search terms in the help section we’ve created
• Via the “settings” button you have the option to hide or unhide keywords of the help section

This point concludes the point regarding “content-based help”

Conclusion

Running a script is an easy thing but be sure of the effects of the script on your environment and how it behaves globally can be challenging especially if you are not the author of the script.
My own experience shown me multiple times that adding comments or help section in a script could be useful to everyone who runs it.
That’s why since a while, my rule of thumb is to include a help section and comments in my scripts to be sure that others will be confident when running the script. Also if needed, they will propose more easily improvments as they have a clear understanding of the code.

So help yourself and others by creating “content-based help” which I consider the manual of your script and add comments to specific areas of the script to remove potential questions.

I hope this post helped you,
Dont’ hesitate to comment,
Your host,

You can always reach me here:

• Facebook
• GitHub
• LinkedIn
• Twitter