如何创建描述性 PowerShell 注释

当 PowerShell 新手开始编写脚本时，他们通常会关注代码。毕竟，代码是让事情发生的关键！可执行代码显然很重要，但是当您编写了这么多代码而忘记了它的作用时会发生什么？这时 PowerShell 注释就可以发挥作用了。

如果你在一个团队中，他们理解你正在编写的代码吗？ PowerShell 注释可以提供帮助。

在脚本中编写描述性且信息丰富的 PowerShell 注释可以帮助我们人类理解代码的意图、结果，或许还可以描述一次遇到的边缘情况。

在本文中，您将了解 PowerShell 中不同类型的注释、要使用哪些注释以及如何在脚本中有效地使用它们。

使用单行 PowerShell 注释

您是否曾经编写过一些代码，但必须在几周或几个月后对其进行审查？大概。这么久之后你明白了吗？也许不会。如果您在代码中留下一些有用的注释就好了！

大多数编程语言都有注释的概念。 PowerShell 也不例外。在 PowerShell 中，您的朋友是 #。 PowerShell 将同一行中主题标签 (#) 后面的所有内容作为解释代码忽略。

下面的示例代码是一个脚本的摘录……好吧，您可以参考第一行的 PowerShell 脚本注释来了解它的作用。如果您是 PowerShell 专家，您可能可以指出此代码片段的用途，而无需添加注释。

# Get all files with TXT extension, show the name of each file and then delete them.
Get-ChildItem *.TXT | ForEach-Object {
    Write-Output $_.FullName
    Remove-Item $_.FullName
}

但是，当您遇到像下面这样的简洁命令时该怎么办？

"{0},{1}" -f [bool](gm -input (1..20) -name count), (1..20).count

添加注释将为您或任何最终将阅读您的代码的人提供很好的服务。如下所示，在简洁命令上方添加注释对于理解代码有很大的不同。

#Check whether the object has a property named "count". Then, return true or false.
"{0},{1}" -f [bool](gm -input (1..20) -name count), (1..20).count

使用 PowerShell 块注释/多行注释

在上一节中，您了解到注释以 # 字符开头。没有什么可以阻止您创建多行评论。事实上，在PowerShell 2.0之前，创建多行注释的唯一方法是创建多行单行注释。

保持注释简短明了是好事，但某些情况下需要使用 PowerShell 多行注释，也可以称为 PowerShell 注释块。

PowerShell 中的注释块以 结尾。以下是评论块何时适用的一些示例。

将长注释分成多行

有时脚本中不可避免地会有很长的注释。这些长评论可能远远超出您当前的显示框架。发生这种情况时，您将需要继续水平滚动才能阅读整个注释行。

例如，不要使用长单行注释，例如：

# It is sometimes unavoidable to have a long comment in a script. These long comments can go way beyond your current frame of the display. And when that happens, you will need to keep on scrolling horizontally to read the entire comment line.

为什么不将其变成更容易阅读的多行注释，如下所示：

<# It is sometimes unavoidable to have a long comment in a script. These long comments can go way beyond your current frame of the display.And when that happens, you will need to keep on scrolling horizontally to read the entire comment line. #>

添加描述性文本

您是否曾经下载或编写过脚本，并将其保存在一些随机或非描述性的名称下？我知道我有！

当您打开脚本来了解它到底是什么时，如果里面列出了有用的详细信息（例如脚本的用途、创建者和创建时间），那就太好了。

PowerShell 中的块注释对于在脚本中添加描述性文本非常有用。这样，脚本的目的就已经给出，也是包含警告或使用脚本时需要注意的事项的好方法。

下面是块注释的示例，描述了脚本是什么、上次更新时间，并且还显示了运行脚本时不应该执行的操作的警告。

<# Using this script will export the email addresses of all mailboxes in the Exchange organization.

WARNING: DO NOT RUN THIS SCRIPT IN THE EXCHANGE MANAGEMENT SHELL.

Last update: Feb 16, 2020
#>

记录要求和步骤

如果您的脚本有特定的执行方式，或者有特殊的运行要求，块注释将有助于在脚本或函数中记录它。

下面是使用块注释记录需求和步骤的示例。

<#
This function requires an encrypted credential XML file that will be used
to authenticate with Office 365.

If you don't have this yet, follow these steps.

1. Open PowerShell
2. Run this command - 'Get-Credential | Export-CliXml .\credential.XML'
3. Make sure to save the XML file inside the same folder as the script.

NOTE: The credential XML file will only work on the same computer and the same account
used to generate it.
#>

注释掉现有代码

评论不仅仅用于添加评论。您还可以将现有代码行转换为单行注释或块注释。

也许您发现自己正在测试或调试脚本。当代码被注释掉时，PowerShell 会在运行时跳过该代码的执行。

例如，您有一个脚本，用于获取 Active Directory 中的用户列表，并使用 foreach 循环 处理该列表，并使用 Set-AdUser设置每个用户的部门名称> cmdlet。

<#
This script will get all AD users matching the filter
and each user's department name will be changed to 'Finance'.
#>
$adUsers = Get-ADUser -Filter *
foreach ($user in $adUsers) {
    Write-Output "$($user.Name) - Department name will be changed to 'Finance'"
    Set-AdUser -Identity ($user.SamAccountName) -Department 'Finance'
}

但是，如果您想在不运行 Set-AdUser 行的情况下测试 foreach 循环，那么您只需注释掉该特定行，如下所示：

foreach ($user in $adUsers) {
    Write-Output "$($user.Name) - Department name will be changed to 'Finance'"
    #Set-AdUser -Identity ($user.SamAccountName) -Department 'Finance'
}

现在可以安全地测试脚本，而无需实际更改每个用户的部门名称。

提示：在 Visual Studio Code 中，您可以通过按“CTRL + /”键盘快捷键注释掉一行或多行。

现在，如果您想注释掉多行，可以选择在每行开头放置 #，也可以将多行括在 内。 块如下例所示。正如您所看到的，整个 foreach 循环已变成块注释。

$adUsers = Get-ADUser -Filter *
<# foreach ($user in $adUsers) {
    Write-Output "$($user.Name) - Department name will be changed to 'Finance'"
    Set-AdUser -Identity ($user.SamAccountName) -Department 'Finance'
} #>

提示：在 Visual Studio Code 中，您还可以通过突出显示一行或多行代码并按“ALT + SHIFT + A”键盘快捷键来创建注释块。

基于评论的帮助

当您想让您的脚本或函数看起来更专业时，您可以通过添加基于注释的帮助来实现。基于注释的帮助是块注释中包含的关键字和文本的集合。

访问页面 - 关于基于评论的帮助 - 了解有关基于评论的帮助关键字和语法的更多信息。

下面的示例代码演示了一个名为 Get-WhatTimeIsItNow.ps1 的脚本，其中包含基于注释的帮助。

<#
.SYNOPSIS

Short description of the script.

DESCRIPTION

Long description of the script

.EXAMPLE

PS C:\> Get-WhatTimeIsItNow.ps1

Explanation of what the example does

.INPUTS

Inputs (if any)

.OUTPUTS

Output (if any)

.NOTES

General notes
#>

Get-Date -Format t

基于注释为您的脚本提供 Get-Help 支持。这意味着当您运行 Get-Help 时，PowerShell 将返回脚本中包含的“帮助”文本，如下所示。

提示：在 Visual Studio Code 中，您可以通过在编辑器窗格中键入 comment-help 来插入默认的基于注释的帮助块。

最佳实践

以下是一些您可能称之为创建有效评论的最佳实践。这些绝不是硬性要求，而是许多人已经付诸实践的建议，您可以将其用作指南。

不要在评论中引用行号

编写代码时，您可能会想在注释中添加对行号的引用。您的想法可能是正确的，添加行号引用会使您的代码更容易理解。也就是说，如果您确定您的代码永远不会被修改。

想象一下，脚本中插入了一行新代码。这意味着您评论中的所有行号引用都已经发生了变化。为了保持行号准确，您必须编辑注释以一一更新它们。

不要在脚本后添加注释

我们人类习惯于从上到下阅读。如果您添加的注释对于后续代码行很重要，那么在之前添加注释是合乎逻辑的。

毕竟，如果您要在脚本中添加有关脚本的注释，那么将注释放在代码之前而不是之后不是更明智吗？

不要在行尾添加注释

和前面的例子一样，把注释放在代码后面，即使是在同一行，也不比把注释放在代码下面好。

在代码末尾添加注释可能会导致编辑错误，因为您不仅不能专注于修改代码，还必须注意注释会随着代码的更改而移动。

不要陈述显而易见的事情

有时代码太简单，意图已经太明显，添加注释只是一种浪费。通常在这种情况下，注释甚至可能比它引用的代码还要长。

如果您认为代码是不言自明的，您可能需要考虑跳过添加注释。

概括

在本文中，您了解了向 PowerShell 脚本或函数添加注释的重要性。您还了解了可用的不同类型的注释，以及正确制作和放置的注释如何显着提高代码的可读性。

关于如何在 PowerShell 中应用注释没有硬性规定，但有关于如何使用它们的经过测试和验证的建议。最后，您可以决定如何在脚本中使用注释来从头到尾提醒您重要的事情。

进一步阅读

• 关于基于评论的帮助
• 构建高级 PowerShell 函数和模块 - 基于评论的帮助（视频）
• 关于 PowerShell 评论的六条评论