最佳实践成就完美

在过去的几周里，我一直在分享和演示编写有效的 PowerShell 函数的技术。我知道我已经提到了一些推荐的最佳实践。但由于它们很重要，所以我想回顾并重新强调它们。这些实践将使您的代码更易于编写、更易于调试或排除故障并且更安全。我想其中一些是简单的常识，但有时我们需要有人提醒我们。这些项目没有任何特定的顺序。

遵循命名约定

使用动词-名词命名约定为您的函数指定一个有意义的名称。您可以为 .ps1 脚本文件指定任何适合您的名称，但函数应遵循动词-名词命名约定。如果我无法通过运行 Get-Verb 找到你的函数的动词部分，那么你就做错了。我知道有时找到正确的动词可能很棘手。但要找到尽可能接近的东西。您始终可以使用您希望的任何动词为您的函数创建别名。

名词应该是单数，尽管我有时会违反这一规则。使名词有意义且具体。如果存在命名冲突的可能性，请考虑为名词添加前缀。前缀可以是您姓名的首字母缩写，也可以是组织的缩写。前缀应该消除命名冲突并使识别命令更容易。

如果出现命名冲突，您可以使用其完全限定名称运行命令：

smbshare\get-smbshare

使用命令名称指定命令的模块名称。

另一个重要的命名约定是避免脚本中使用别名。在控制台提示符下以交互方式运行 PowerShell 时，可以随意使用别名。但在脚本中，请使用完整的 cmdlet 名称和参数名称。我建议甚至使用参数名称作为位置参数。如果您使用像 VS Code 这样具有 Intellisense 功能的编辑器，那么这并不是太大的负担。您只需编写一次代码，因此第一次就以正确的方式编写。

也就是说，您可以随意使用您想要的所有别名在 VSCode 中编写您的函数。完成后，使用 VSCode 扩展您的别名。您可以使用命令选项板或键盘快捷键中的命令。

请注意，这将不会添加缺少的参数名称。

由于 PowerShell 命令的设计方式，如果您使用完整的命令和参数名称，它实际上是自记录的。

无密码

我想这是理所当然的，但如果您需要提醒，请不要将任何密码或凭据硬编码到您的脚本和函数中。

$pw = "Open$esame!"
...
foo.exe /u administrator /p $pw

另外，还要避免这种情况：

Param(
[string]$Name,
[string]$Password
)

如果您的命令需要密码，请让用户输入 PSCredential。

Param(
 [pscredential]$Credential
)

这并不意味着需要提前创建凭证对象。用户可以指定用户名，PowerShell 将提示输入密码。

另一种选择是集成 Microsoft 的 SecretStore 和 SecretManagement 模块。

保持不可知论

您的 PowerShell 代码应该是不可知的。我的意思是它不应该对域名之类的东西有硬编码值。这是不好的形式。

$domain = "ContosoCorp.pri"

至少，使用 PowerShell 填充该值。

$domain = (Get-ADDomain).DNSRoot

您还可以将其作为参数并让用户指定一个值。或者，这是一项高级技术，编写函数以使用 .psd1 文件中的配置数据。

如果你不能在不先清理代码的情况下向我展示你的代码，我会说你做错了什么。可能感觉您节省了时间，但我认为这实际上使您的代码变得不太安全。

评论数

我们总是谈论内部文档的需求。阅读 PowerShell 代码应该像阅读故事一样。您应该能够遵循该操作。如果您使用完整的 cmdlet 和参数名称，则可以处理大部分工作。如果您包含有意义的 Write-Verbose 消息，那也将填补空白。仅当运行可能难以理解的 .NET 代码块或需要解释为何使用当前代码的脚本部分时，才需要添加注释部分。随着代码的成熟和更新，插入包含关键更改的注释可能会有所帮助。

代码注释对你和下一个人来说都是一样的。您可能是六个月后查看代码的人，努力弄清楚您想要实现的目标。

让它变得漂亮

我记得在我使用 VBScript 的时候。一位论坛成员的代码有问题。我主动提出提供帮助，他发布了他的代码。这是数百行单行距、左对齐的代码。根本无法阅读，而且 VBScript 已经够难的了。缩进和空白很重要。我刚刚提到你的代码应该讲一个故事。代码在文件中的显示方式可以帮助讲述这个故事。空行或空白不会造成性能损失。如果您的代码更易于阅读，则调试和故障排除也更容易。

最简单的方法是在 VS Code 中编写函数。右键单击编辑器窗格，选择“设置文档格式”或使用键盘快捷键。

当我第一次看到它的实际效果时，感觉就像魔法一样，正是这把我推向了 VS Code 的怀抱。您还可以配置 VSCode 在每次保存文件时格式化文件。

概括

我希望你们中的许多人已经遵循这些建议。如果没有，我想知道为什么。您可以对本文发表评论。也许我可以澄清或提供更多背景信息。查找要在 PowerShell 脚本项目中使用的代码只是工作的一部分。如何使用代码同样重要。