Surely you already use comments within your PowerShell scripts and surely you too have been annoyed by uncommented scripts.
Comments in PowerShell scripts make it possible to document certain processes directly in the code. Furthermore, additional notes can be added to code snippets – for example, if a function is to be extended by further features.
But beyond this pure information content, comments in PowerShell, used correctly, can be used for help articles about your functions. In this article, I’ll show you how to use meta-data to get script information via Get-Help.
The magic word for our project is Comment-Based Help.
As the name suggests, this method allows us to generate help information through comments. These comments have to be arranged and formatted correctly – you’ll find out exactly how in this section.
In principle, we can distinguish between two types: Comment-Based Help for Functions and for Scripts. The former goes one layer deeper and starts with functions, which we want to provide with meta-data. However, if your code is not prepared in functions, it is also possible to provide a whole script with this information.
Before we look at their exact usage, I list all keywords for the Comment-Based Help here:
Keywords for Comment-Based Help
Short description of the script or function
Detailed description of the code
Description of a used parameter. Keyword is used several times (1x per parameter). The parameter must be named additionally after the keyword!
Description of possible objects that can be passed into the function via a pipeline.
Output values of the function
Additional information about the code
URL to the corresponding online help (if available)
In order not to go beyond the scope of this article, I will limit the listing to the keywords that are used most often. You can find more keywords in the Microsoft Docs.
The keywords listed above are notated in a specific format in the code. This looks like the following:
Notation of Help Keywords and Content in the PowerShell Script Header
The keywords are headed with a period – the corresponding text is placed below the keyword. The keyword block is commented out using “<##>”.
Comment-Based Scripts and Functions differ in the sense that the Comment block is placed differently. For functions, it is best to place the block under the function name. Other possibilities are to place the block directly in front of the function (without a blank line) or at the end of the function body.
If scripts are to be equipped with the information, the Comment block is set directly at the beginning of the code – logically, this then also contains information about the script as a whole and not about partial sections.
Example and Usage of Comment-Based Help
In the following, we will show how Comment-Based Help can be used in practice by means of a function that outputs all directory and file objects of a certain directory up to a certain hierarchy depth.
PowerShell already provides this functionality – the following example only serves for understanding.
The aim now is to describe the functionality by means of descriptions, examples and parameter information in a help article.
Meta-data in the function header
In this code a holistic help comment has now been written. On a Get-Help call on this information, we now get the following output in the console:
Output from Get-Help Get-ChildItemDepth
The -Examples parameter can also be used to output all available examples:
In principle, it can be said that Comment-Based Help offers great benefits for IT departments. Not only can you get a quick overview of the self-built functions yourself, but colleagues don’t have to fight their way through numerous lines of code to guess the basic functionality.
Due to its limited length, the script name can only ever give a rough indication of a script’s function without being able to go into detailed information. This way of creating help also saves the need for external documentation of the code.
If there is a basic policy or code-of-conduct that explicitly requires the use of these help sections, I can strongly recommend the Pester module. It can be configured to check the code for the presence of help articles before each release. You can even check if every single parameter has a description.
https://www.scriptrunner.com/wp-content/uploads/2021/03/powershell-best-practices.png10001000Philip Lorenzhttps://www.scriptrunner.com/wp-content/uploads/2018/05/ScriptRunner_Logo_RGB-300x45.pngPhilip Lorenz2021-03-10 10:00:042021-03-10 15:22:175 PowerShell Scripting Best Practices – From Runnable to Professional CodeScriptRunner Software GmbH