Как добавить комментарий в PowerShell

При написании кода на любом языке важно добавлять комментарии. Это также относится к вашим скриптам PowerShell. Хотя они могут быть иногда короткими, добавление комментариев в PowerShell тем не менее важно.

Комментарии не только помогают другим понять ваш код, но и служат отличным напоминанием для вас самих, когда вы читаете свой код. Их можно использовать для объяснения функций или при тестировании вашего скрипта, чтобы закомментировать части вашего скрипта.

В этой статье мы рассмотрим, как добавить комментарий в PowerShell и как использовать блоки комментариев.

Комментарий в PowerShell

Так же, как и во многих языках программирования, мы можем использовать # для добавления комментария в PowerShell. При добавлении комментариев к вашим скриптам всегда старайтесь объяснять свои мысли или обоснования. Или кратко опишите, что делает функция.

Причина этого заключается в том, что хорошо написанный скрипт PowerShell часто довольно очевиден. Если вы посмотрите на приведенный ниже пример, комментарий на самом деле не добавляет никакой ценности к коду.

Get Admins
$admins = Get-Admins

В этом случае лучшим вариантом может быть объяснение того, что мы получаем:

Get all users that have an admin role
$admins = Get-Admins

Комментарии также могут использоваться для комментирования части вашего кода или функции. Это часто бывает полезно, когда вы тестируете свой скрипт и хотите пропустить его часть. Просто добавьте # перед функцией, которую вы хотите пропустить, и PowerShell проигнорирует эту функцию.

Например, в небольшом скрипте ниже мы создаем 10 тестовых файлов. Чтобы протестировать ваш скрипт без фактического создания файлов, вы можете, например, закомментировать командлет New-Item. Таким образом будет выполнена только функция Write-Host.

Path for the test files
$path = "C:\temp"

Create 10 test files in the given path
1..10 | % {
    $newFile = "$path\test_file_$_.txt";
    # New-Item $newFile  # This cmdlet is skipped due to # infront of it
    Write-Host $newFile
}

Комментарий блока PowerShell

В общем, рекомендуется делать ваши комментарии короткими и по сути. Но в некоторых случаях вам нужно несколько строк, чтобы объяснить, что делает функция. Для комментариев длиной до двух строк нормально использовать # перед каждой строкой.

Но когда вам нужно больше, тогда проще и лучше использовать блочную комментарий в PowerShell. Преимущество блочного комментария заключается в том, что его можно легко редактировать, сворачивать в вашей среде разработки (например, в Visual Studio), и они легче для чтения.

Как вы можете увидеть из приведенного ниже примера, # работает нормально, когда вам нужно всего две строки для вашего комментария:

Storing the path of the log file for easy modification
Changing this variable updates the log file location throughout the script.
$LogFile = "C:\Logs\output.log"

Но когда комментарии длиннее, блочные комментарии становятся более полезными и удобными для чтения. Чтобы создать блочный комментарий, вы начинаете его с <# и заканчиваете блок комментария с #>:

<#
    Get all the permissions of each mailbox
    
    Permission are spread into 4 parts.
    - Read and Manage permission
    - Send as Permission
    - Send on behalf of permission
    - Folder permissions (inbox and calendar set by the user self)
#>

Помощь по функциям на основе комментариев

Ваши скрипты, а также функции, должны всегда начинаться с блока комментариев. Этот блок комментариев написан в определенном формате, который облегчает чтение и также позволяет нам отображать информацию с помощью команды help.

Этот формат известен как помощь на основе комментариев. Он написан внутри блока комментариев PowerShell и использует ключевые слова помощи для форматирования блока комментариев. Помощь на основе комментариев состоит из нескольких секций. Не обязательно включать их все, но рекомендуется добавить Сводку и хотя бы один пример использования функции.

function Get-UserInfo {
    <#
    .SYNOPSIS
        Get the Microsoft 365 user information
    .EXAMPLE
        Get-UserInfo -Username 'meganb@contoso.com'

        This will get the M365 information of the given user
    #>
    [CmdletBinding()]
    param(
        # Microsoft 365 username
        [Parameter(Mandatory = $true)]
        [string]$Username
    )
    # Rest of the function code
}

Лучше всего помещать раздел помощи на основе комментариев внутри вашей функции, а не выше нее. Таким образом, сложнее забыть обновить комментарий, когда вы вносите изменения в функцию.

Если ваша функция использует параметры, убедитесь, что вы добавили комментарии к каждому параметру, объясняющие, какую информацию вы ожидаете.

В начале скрипта часто добавляют больше информации. Например, более длинное описание того, какова цель скрипта, несколько примеров, как использовать скрипт, и раздел с примечаниями, где можно добавить такую информацию, как дата последнего изменения, автор и т.д.

<#
.SYNOPSIS
    A short one-line action-based description, e.g. 'Tests if a function is valid'
.DESCRIPTION
    A longer description of the function, its purpose, common use cases, etc.
.NOTES
    Information or caveats about the function e.g. 'This function is not supported in Linux'
.LINK
    Specify a URI to a help page, this will show when Get-Help -Online is used.
.EXAMPLE
    Test-MyTestFunction -Verbose
    Explanation of the function or its result. You can include multiple examples with additional .EXAMPLE lines
#>

Использование справки на основе комментариев

Когда вы добавили блок помощи на основе комментариев в свой скрипт или функцию, это позволяет вам просматривать эту информацию с помощью команды get-help в PowerShell. Если вы выполните команду без каких-либо параметров, то она отобразит только синопсис, описание и синтаксис функций.

Но мы можем использовать параметры, чтобы показать дополнительную информацию из раздела помощи на основе комментариев:

-Подробно Предоставляет более подробную информацию о команде, включая примеры.
-Примеры Показывает примеры использования команды.
-Полный Показывает полный текст помощи, включая подробные описания и примеры.
-Online Открывает онлайн документацию для команды в веб-браузере по умолчанию.

Таким образом, если мы хотим просмотреть подробную информацию о моем скрипте статуса MFA с примерами, то мы можем сделать следующее:

Get-Help .\Get-MgMFAStatus.ps1 -Detailed

Завершение

Важно добавлять комментарии в ваш PowerShell, когда вы пишете скрипт. Функции могут казаться совершенно логичными, когда вы их пишете, но если вам нужно обновить скрипт через 6 месяцев, комментарии могут действительно помочь вам понять ваш собственный код и мысли 😉

Надеюсь, эта статья помогла вам лучше понять, как использовать комментарии в PowerShell. Если у вас есть вопросы, просто оставьте комментарий ниже.