第一人称评论是否分心且不专业？

我只是发现自己在我正在编写的某些代码（旧式Visual Basic 6.0）中写了以下评论：

If WindowState <> 1 Then
    'The form's not minimized, so we can resize it safely
    '...
End if

我不确定为什么在评论中下意识地使用“我们”。我怀疑这是因为我想象有人在逐步执行代码，就像他们实际上在“执行”每一行上的所有命令一样，而不是仅仅看着它们发生了。以这种心态，我本可以使用I can resize it，因为我是目前正在“做”的那个人，或者you can resize it好像我正在与将来正在“做”的那个人说话，但是由于这两种情况最有可能碰巧，我使用“我们”，就好像我在引导别人通过我的代码一样。

我可以简单地将其重写为it can be resized并避免出现此问题，但这激起了我的好奇心：在评论中使用这样的第一人称是常见的，还是被认为分散了注意力和/或不专业？

评论应该写给人类理解。当人们交流时，我们通常使用“ I”，“我们”，“您”等。

当某人试图理解某些代码时，有两个或多个参与者：阅读该代码的人以及该代码的原始作者。说“我们”很好。除非“专业”，否则您的意思是“类似机器人”。

我建议不要使用“ I”，因为它会自动承担代码的全部责任。如果其他人正在阅读它，那看起来会很糟糕，因为在这种情况下，这是团队合作的结果。我对使用“我们”无动于衷。但是，它可能会真正地包括其他读者一样出现。

我的投票仍然简洁明了。如果可以用不太冗长的方式传达消息，为什么还要选择其他内容？因此，关于这个例子，我会写：

'The form is not minimized so it can be resized safely.

我采用两种方法之一，通常是听起来更好的方法。

在解释诸如需求或合理性之类的事情时，我赞成“我们”，因为您在那里：

// We can't proceed unless the user has given us this information.

如果我在解释该过程，那么我倾向于使用命令式（命令式）声音（如果输入错误的话，请纠正我）：

// Get the foo from bar and make sure it follows our required format.

后者可能很危险地接近于重复代码，但是有一定的用途。因此，它不是在使用“我”或“我们”，而是实际上意味着“您”。

我认为这只是学术/技术写作风格的一种变体，通常是非个人的。使用被动语态，使用“皇家我们”（“一个”已过时）。

作为一般规则，它是非特异性谁无论如何都会使用它-的注释是维护中获益，而不是通常只对原作者的。

就是说，我经常在评论中使用第一人称-解释为什么我做出特定决定以及我在想什么。

注释应该告诉您为什么要做某事，而不是做什么。如果从代码中看不到正在执行的操作，请修复代码，而不只是添加注释。第一人称，第二人称等并不重要，重要的是传达必要的信息。

如果您必须讲述代码，请使用命令式命令，例如

'ensure that the window is not minimized
If WindowState <> 1 Then
    'resize the window
    '...
End if

（并且请不要在代码中使用诸如“ 1”之类的裸常量）

也许我们指的是使魔术发生的程序中的小家伙？:)

英语被动语态很难使用，听起来也很糟糕。人们喜欢使用人格形式（我，您，我们一个）。

例：

（您/我们/一个必须）使用委托将窗口调整大小事件传递给父对象

必须使用委托将窗口调整大小事件传递给父对象

另一个示例（请注意，您经常可以在评论中省略人形）：

（我们）发现了一个例外。（我们将）显示一个错误对话框。

捕获到异常，将显示错误对话框。

PS。在英语中用“ you”代替被动语非常普遍，以至于它也开始渗入其他语言。在芬兰语中，第二人称单数形式存在（例如英语“ thou”），听起来非常可笑。

如果您在谈论程序的执行，则不是“我们”，“您”或“我”。拟人化可能非常普遍，以至于不为人所知，但这是一种危险的习惯（PDF警告。Dijkstra警告。）：

我认为拟人化是最糟糕的。我现在已经看到了“尝试做某事”，“想要做某事”，“相信某事是真实的”，“知道某事”等程序。不要天真地相信这种语言的使用是无害的。它邀请程序员在执行程序时标识自己，并几乎迫使他使用操作语义。

我不认为第一人称视角或“皇家我们”似乎都不专业，也不会使人分心。我确实认为我们应该努力用E-Prime来写英语注释，E-Prime是不具有“成为”动词的英语子集。

如果您在注释中过度使用“ be be”，您将得到令人困惑的陈述，例如：

// X is 10
// X is the user data of the newly-authenticated user
// X is a BigInt

好吧，也许不是一次全部，但是等距确实会使评论不清楚。

我认为，在E-Prime中编写要求可以使这些要求更加明确，因为作者必须在执行过程中指出一个演员。

正确的评论方式是第三人称非人称。“ 表单没有最小化，因此可以安全地调整大小 ”。

• 我天真。
• 你真傻
• 我们太正式了（太贵了）。

每个句子都可以用这种方式改写（见上文），这是唯一的专业写作方式。

这取决于评论。

通常，我按照《牛的嘴》建议的方式发表评论。我也总是以这种方式编写文档生成的注释（Doxygen，JavaDoc）。

但是，许多人常常忽略了使用版本控制来识别谁在源文件中写/触过行。有时候说“ I”是适当的，尤其是当很容易将“ I”追溯到编写代码的人时。如果您作为个人做出决定，建议您使用“ I”（以及版本控制）来识别和跟踪与代码一致的决定。

我的好父亲（mhrip）会问：“您还有其他重要的事情要打扰吗？”

但是，就我个人而言，我喜欢“我们”。考虑到我是公司的唯一员工，我也想知道为什么我要用上游文档而不是代码来编写我们。

但是，我自己和我都同意，这样我们可以减少孤独感：)

我是唯一写“我们”并认为“我和计算机”（或“我的团队和计算机”）的人吗？“我们”将处理外部给我们的请求，这意味着“我们”需要阅读请求，打开一些窗口，并根据“我们的”业务需求进行一些计算。这也有助于将代码视为您自己而不是敌人的一部分:-)

对于简短的评论，有时我会以第二人称写出来，就像我在指示其他人一样，几乎是作为一条消息发送给下一个开发人员阅读评论。如

//You can get a session_id from SYSSession.getSessionID() if you need one

较长的注释（例如较长的函数标头或几行算法描述）我尽量保持中立，不要采用第一人称，第二人称或第三人称。

您添加了此评论是因为代码不够清晰。我通常会发现，通过定义明确的方法来表达意图可以避免使用注释。例如，该行可能已移至名为的方法CanThisFormBeResized。

一个好名的方法，不管多么小，都会引起注释，因为注释和代码很容易不同步。

因此，如果大多数注释都可以用代码表示，那么留下注释的理由就很少了。

• 如果您的意见是您的意见，请以“ I”开头
• 如果您认为自己的评论应该是共同的观点（例如最佳实践），那么请以“我们”开头
• 如果您的评论针对的是半智者编写的一些狡猾的代码，则请删除该评论并走过去，将其与同事混淆的代码打通，然后与他们面对面解决。

根据经验，我建议使用第一人称I。

为什么？不是因为我的所有格性质，而是因为当人们以任何其他角度说话时，他们倾向于使用过多的单词或使句子过于复杂，从而迷失了试图解释事物的能力。第一人称往往总是最容易阅读。

我个人会用C＃编写：

if (WindowState != WindowState.Minimised)
{
     ResizeWindowSafely();
}

或类似的东西，因此不需要注释。