VS Code is my coding tool of choice. I love that one lightweight editor can do so much and as PowerShell is usually the language that I write in I really love the PowerShell extension
Help
When you write a PowerShell function that is going to be used by someone other than you, you don’t want to be the guy or gal that has to support it indefinitely. You should write good help to enable your users to simply type
Get-Help NAMEOFCOMMAND
and get all of the help that they need to use the command
If we look at one of my favourite dbatools commands Get-DbaLastGoodCheckDB we can see this in action.
Get-Help Get-DbaLastGoodCheckDb -full
This returns
NAME
Get-DbaLastGoodCheckDb
SYNOPSIS
Get date/time for last known good DBCC CHECKDB
SYNTAX
Get-DbaLastGoodCheckDb [-SqlInstance] [[-SqlCredential] ] [-Silent] []
DESCRIPTION
Retrieves and compares the date/time for the last known good DBCC CHECKDB, as well as the creation date/time for the database.
This function supports SQL Server 2005+
Please note that this script uses the DBCC DBINFO() WITH TABLERESULTS. DBCC DBINFO has several known weak points, such as:
– DBCC DBINFO is an undocumented feature/command.
– The LastKnowGood timestamp is updated when a DBCC CHECKFILEGROUP is performed.
– The LastKnowGood timestamp is updated when a DBCC CHECKDB WITH PHYSICAL_ONLY is performed.
– The LastKnowGood timestamp does not get updated when a database in READ_ONLY.
An empty ($null) LastGoodCheckDb result indicates that a good DBCC CHECKDB has never been performed.
SQL Server 2008R2 has a “bug” that causes each databases to possess two dbi_dbccLastKnownGood fields, instead of the normal one.
This script will only displaythis function to only display the newest timestamp. If -Verbose is specified, the function will announce every time
more than one dbi_dbccLastKnownGood fields is encountered.
PARAMETERS
-SqlInstance
The SQL Server that you’re connecting to.
Required? true
Position? 1
Default value
Accept pipeline input? true (ByValue)
Accept wildcard characters? false
-SqlCredential Credential object used to connect to the SQL Server as a different user
Required? false
Position? 2
Default value
Accept pipeline input? false
Accept wildcard characters? false
-Silent []
Use this switch to disable any kind of verbose messages
Required? false
Position? named
Default value False
Accept pipeline input? false
Accept wildcard characters? false
This cmdlet supports the common parameters: Verbose, Debug,
ErrorAction, ErrorVariable, WarningAction, WarningVariable,
OutBuffer, PipelineVariable, and OutVariable. For more information, see
about_CommonParameters (http://go.microsoft.com/fwlink/?LinkID=113216).
INPUTS
OUTPUTS
NOTES
Copyright (C) 2016 Jakob Bindslet (jakob@bindslet.dk)
This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by
the Free Software Foundation, either version 3 of the License, or (at your option) any later version.
This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.
You should have received a copy of the GNU General Public License along with this program. If not, see .
————————– EXAMPLE 1 ————————–
PS C:\>Get-DbaLastGoodCheckDb -SqlInstance ServerA\sql987
Returns a custom object displaying Server, Database, DatabaseCreated, LastGoodCheckDb, DaysSinceDbCreated, DaysSinceLastGoodCheckDb, Status and
DataPurityEnabled
————————– EXAMPLE 2 ————————–
PS C:\>Get-DbaLastGoodCheckDb -SqlInstance ServerA\sql987 -SqlCredential (Get-Credential sqladmin) | Format-Table -AutoSize
Returns a formatted table displaying Server, Database, DatabaseCreated, LastGoodCheckDb, DaysSinceDbCreated, DaysSinceLastGoodCheckDb, Status
and DataPurityEnabled.
Authenticates with SQL Server using alternative credentials.
RELATED LINKS
DBCC CHECKDB:
https://msdn.microsoft.com/en-us/library/ms176064.aspx
http://www.sqlcopilot.com/dbcc-checkdb.htmlData Purity:
http://www.sqlskills.com/blogs/paul/checkdb-from-every-angle-how-to-tell-if-data-purity-checks-will-be-run/
https://www.mssqltips.com/sqlservertip/1988/ensure-sql-server-data-purity-checks-are-performed/
So anyone who needs to use the command can see what it is, a full description, what each parameter is for, some examples and some links to more information
So what I used to do was put a snippet of code like this at the top of my function and then fill in the blanks
<# .SYNOPSIS Short description .DESCRIPTION Long description .EXAMPLE An example .PARAMETER Parameter Help .NOTES General notes .LINK Link to more information #>
The latest release of the PowerShell extension for VS Code has made that process so much simpler 
Thank you David and Keith
Now you can simply type <# and your help will be dynamically created. You will still have to fill in some of the blanks but it is a lot easier.
Here it is in action in its simplest form
But it gets better than that. When you add parameters to your function code they are added to the help as well. Also, all you have to do is to tab between the different entries in the help to move between them
Now when we run
Get-Help Invoke-AmazingThings -Full
We get this
Nice and easy and a great feature added to the VS Code PowerShell extension
