#PowershellBasics: Comments and comment based help


May 13, 2021 by Kenneth Fisher

I’ve talked about SQL Server comments before and how important they are. In PowerShell comments are important for all the same reasons and then some. So first of all in SQL Server we use the following for comments:

-- Line comment
/* Block comment */

In Powershell we use these:

# Line comment
<# Block comment #>

Commenting your code, still super important. That piece of code that looks a bit strange because you couldn’t find another way to make it work? Better put in a note why so the next person doesn’t have to spend hours figuring out what you did and why. That block of code that pulls a list of zip files and unzips them? Explain what you are doing. The next person to look at this (who just may be you) could use a hint as to what you were thinking. Weird variable name? Heck, not so weird variable name. It couldn’t hurt to explain the purpose. Did I ever tell you I got a job because I did such a good job commenting my code during a technical test?

Interestingly though PowerShell has a really cool trick that makes comments even more useful and important.

A properly set up comment block gets picked up by Get-Help to create comment-based help. For example:

function Get-Function { }

This is what Get-Function does.

Now if you use Get-Help on Get-Function you have a description section. These aren’t exactly complicated, but on the other hand they do appear to be somewhat fiddly. Rather than go over in detail how this works I’m going to recommend that you follow the link above and read about it.

5 thoughts on “#PowershellBasics: Comments and comment based help

  1. Chad Estes says:

    Small edit needed:

    /# Block comment #/

    should be

  2. […] Kenneth Fisher stands on one foot: […]

  3. […] a big fan of comments (MSSQL, Powershell), so along those lines here’s an interesting way to comment an IF-THEN-ELSE […]

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s

This site uses Akismet to reduce spam. Learn how your comment data is processed.

Enter your email address to follow this blog and receive notifications of new posts by email.

Join 3,753 other subscribers

Follow me on Twitter

ToadWorld Pro of the Month November 2013
%d bloggers like this: