PowerShell 块评论 | PowerShell 块注释指南

PowerShell评论简介

对于任何程序员来说，对代码的注释与代码的功能一样重要。注释对于编程很重要，因为它可以帮助程序员理解其他程序员开发的代码和功能。在脚本中编写描述性且富有洞察力的 PowerShell 注释可以帮助我们人类理解代码的含义、效果，并可能解释过去出现的边缘情况。本文将详细介绍不同类型的注释，以及何时何地在脚本中有效使用哪种注释。

语法：

在PowerShell中注释时使用#。同一行中 # 后面的所有内容都被 PowerShell 解释器视为注释。这用于单行注释、多行注释或使用注释块。

例如：

#example of single ling comment
Write-Host "The above line won't be printed"
<#
the below lines
won't be printed"
#>
Write-Host "above lines are example of multiline comment r script block"

输出：

使用快捷方式注释：

要单独注释掉每一行 (#)，请选择一行或多行并按 Ctrl + Q，或单击注释（在“主页”选项卡的“编辑”部分中）。突出显示代码块并按 Ctrl + Shift + Alt + Q，或选择“块消息”以添加注释块。 （PowerShell Studio 版本 4.1.72 引入了“块注释”图标。）要删除注释（任一格式），请选择要删除的行，然后按 Ctrl + Delete。可以使用 Ctrl +shift+ Q 删除注释，或者选择块并从选项窗口中选择取消注释。

添加评论描述性文字：

当您打开脚本以查找脚本的作用时，如果里面列出了有用的详细信息（例如脚本的用途、创建者和创建时间），那就太好了。 PowerShell 中的块注释有利于在脚本中添加描述性文本。这样，脚本的目标就已经给出了，并且还非常感谢包含警告或使用脚本时需要注意的事项。

示例：

<# This script will copy items from one site collection to another.
WARNING: Don’t run this in production using system account.
Last update: Feb 14, 2021
Last Updated By: Vignesh Krishnakumar
Last run time: 1 hour 30 mins
Duration: Run every month 15th
Inputs to be supplied: Source site, destination site
Output location: C:\output
#>

出于文档目的创建注释：

有时，脚本应该以某种方式或顺序运行。没有开发过它的人不会知道它。在这种情况下，记录脚本块内的步骤将很有用。

示例：

输入：

<#

此函数以加密方式从 XML 文件中获取凭据以连接到系统

如果 XML 文件不存在，请执行以下操作。

1. 以管理员身份打开 PowerShell
2. 运行此命令 - ‘Get-Credential | Export-CliXml .\test.XML'
3. 将输出保存在与脚本相同的文件夹中。
4. 收到凭据后，调用主函数
5. 一旦脚本运行成功，请检查日志路径中的日志
6. 如果出现任何错误，请复制 id 并前往 CRM 中检查

注意：这仅适用于同一台计算机
#>

评论的最佳实践

切勿在注释中使用行号：

在编写代码时，您可能会想要在注释中关注行号。您会正确地认为添加行号引用会使您的代码更容易理解。也就是说，如果您确定您的代码永远不会被修改。想象一下，替换代码行被插入到您的脚本中。这可能意味着您评论中的每一条道路编号引用都已经发生了变化。为了保持道路编号准确，您需要编辑注释以一一更新。

不要在脚本末尾添加注释：

一般来说，代码是从上到下读取的。如果您添加的注释对于后续代码行至关重要，那么在前面添加注释是合乎逻辑的。毕竟，如果您要在脚本中添加有关脚本的注释，那么在代码之前而不是之后拥有注释不是更明智吗？

避免在行尾添加注释：

和上面的观点一样，把注释放在代码后面，虽然是在同一行，但并不比把注释放在代码下面好。在代码顶部添加注释可能会导致编辑错误，因为您甚至必须注意注释会因为代码更改而移动，而不是专注于修改代码。

如果不需要，请避免评论：

有时代码太简单，因此意图已经太明显，在那里添加注释简直是一种浪费。通常在这种情况下，注释可能比它引用的代码还要长。带有注释的明显命令。如果您认为代码是不言自明的，您将需要考虑跳过添加注释。

基于注释的函数和脚本帮助：

基于注释的帮助被写成一系列注释。注释块中的所有行都被解释为注释。基于注释的帮助主题中的所有行都必须是连续的。如果基于注释的帮助主题后面的注释不属于帮助主题的一部分，则最后一个非帮助注释行与基于注释的帮助的开头之间必须至少有一个空行。关键字定义基于注释的帮助的每个部分。每个基于注释的帮助关键字前面都有一个点。关键字可以按任意顺序出现。关键字名称不区分大小写。例如，Description 关键字位于函数或脚本的概要之前。

结论

因此，本文详细解释了 PowerShell 中的注释或注释块。它还解释了可用的各种快捷方式以及每种评论类型的用法。要了解更多详细信息，建议编写示例脚本并进行练习。

推荐文章

这是 PowerShell 块注释的指南。这里我们讨论简介、语法以及 Kotlin 中过滤函数如何工作？并举例说明。您还可以查看以下文章以了解更多信息 -