Use Regions for PowerShell Comments

Doctor Scripto

Summary: Microsoft Scripting Guy, Ed Wilson, talks about combining regions and Windows PowerShell comments in the ISE.

Microsoft Scripting Guy, Ed Wilson, is here. This morning I want to talk about an idea I had the other day when I was on the treadmill. First of all, I will say that walking on a treadmill for an hour is a great way to get some time to think. I often have great ideas when I am walking on the treadmill. At other times, I have some pretty whacky ideas. I think that today’s idea probably falls somewhere in-between.

I have been talking about adding comments to scripts, and yesterday I talked about the importance of adding #TODO tags to document tasks that are left to do on the script. This is not my original idea—in fact, it is a rather standard programing practice.

One thing I will say at the outset is that I do not believe all programming practices are necessarily applicable to writing Windows PowerShell scripts (or any script for that matter). The reason is that scripts are uncompiled code, and by nature, they are not full-blown programming projects.

Beginners should follow some standards, because it will help them write better code, but at the same time, beginners should not be burdened with all of the overhead of a full-blown application. However, as a Windows PowerShell script becomes more permanent, and as it begins to take on the trappings of a mission critical application, proper documentation and programming standards become essential.

One of the good (and bad) things about Windows PowerShell is that it is extremely powerful. As one superhero said, “With great power comes great responsibility.” So look at what your script is doing and what function it fulfills, and adopt the appropriate scripting best practices. I talk about all of these issues (and include guidelines) in my book, Windows PowerShell Best Practices.

Here is my whacky idea—but first, a bit of background

I love using multiline comments in the Windows PowerShell ISE. To me it is much cleaner, and it even gives me the ability to collapse the comment. Here is what I am talking about:

See the little square at the upper-left side of the code? If I click there, the multiline comment collapses. Here is what it looks like when it is collapsed:

Nice little green characters on a single line. Now, how do I create a multiline comment? I begin with a <# and I end with a #>, as shown here:

<#TODO Add an output function

  The output function needs to provide the following:

    1. Output to a file

    2. OUtput to a CSV file

    3. Output to an XML file

    4. Output to a SQL Database

    5. OUtput to email

   #>

So what does this have to do with a region? Well, a region is also collapsible. The advantage of a region is that when it is collapsed, I can tell what is there. This is because I can give the region a name. In this way, it makes my code cleaner and easier to read. Plus I know what is collapsed.

If I put my multiline comment inside a region, when I collapse it, I can tell what is there. Here is what I am talking about—notice that my region contains a #TODO comment:

How did I do this? I added a region by using the #region and #endregion tags. I gave the name TODO Comment to my region, and then inside the region, I added my multiline comment. Here is the code:

#region TODO Comment

 <#TODO Add an output function

  The output function needs to provide the following:

    1. Output to a file

    2. OUtput to a CSV file

    3. Output to an XML file

    4. Output to a SQL Database

    5. OUtput to email

   #>

#endregion

So is it extra work? Yes, a bit. Does it make the code easier to read? When the region is collapsed, it does. Is this something I am going to start doing on a regular basis? I really am not sure. It has the disadvantage of being somewhat as unexpected, and unexpected is more difficult to read.

If I start doing this on a regular basis, I certainly will not do it for all blocked comments. I might do it for only TODO comments because I would normally leave them collapsed. It would be best if I did not have to do this, and when I collapsed a multiline comment, it showed the first line, like the collapsed region does. In this way, I could avoid creating a region when I create a multiline comment. This would require a minor design change.

Add a comment to my blog, and let me know if you like this way of adding a comment. If you like this idea, add it to Connect, and vote it up! Until then, this is how you can achieve the functionality.

That is all there is to combining regions and comments in the Windows PowerShell ISE. Join me tomorrow when I will talk about more cool stuff.

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

Doctor Scripto Scripter, PowerShell, vbScript, BAT, CMD

Follow