Coding style 评论风格：命令式还是第三人称

我有一个关于编程和英语的问题：在评论单行代码时是使用第三人称还是祈使句。 假设以下命令式语言中的代码行应该注释：

object.doSomething();

我评论这一行的方法是使用第三人称将评论放在后面，就像这是一个普通的英语句子，包含这一行作为主语：

object.doSomething(); // does (referencing to the line of code) some action

但是，由于我们使用的是命令式语言，因此实际上“指挥”了计算机，人们甚至可以考虑将注释置于代码之前，并使用命令式：

//Do some action:
object.doSomething();

当需要注释彼此相关的多行时，这甚至非常有用

---

我个人更喜欢第一种风格，但我经常不确定该用什么风格。如果有人能在这里写下他们的个人经历，那就太好了。

第一种方法肯定是更合适的评论方法，因为人们会阅读你的评论。重要的是，它们尽可能容易阅读

//做点什么

听起来像是在和计算机说话，而不是解释代码的作用。

Oracle的官方风格指南指出：

使用第三人称（描述性）而不是第二人称（规定性）。 描述是第三人称陈述式的，而不是第二人称祈使式的。

获取标签。（首选）

拿到标签。（避免）

可以找到Oracle的样式指南。

对于Python，说明了关于docstring的内容（重点添加）：

docstring是以句点结尾的短语。它规定了功能或功能 方法作为命令的效果（“做这个”，“返回那个”），而不是作为描述； e、 g.不要写“返回路径名…”

而且更为明确（增加了强调）：

请注意，所有docstring都以一行摘要开头。总结是 用祈使语气写的（“做”、“用”、“找到”、“返回”、“呈现”， 等）并以句号结束

---

谷歌有明确的指令区分面向接口实现者的文档（解释做什么，命令式风格）和面向库用户的文档（解释它做什么，第三人称风格），这就是你的情况

诚然，这种区别对于行级注释没有什么意义，行级注释总是解释代码的功能

换句话说，这是我的第三人称

---

我认为我见过的最常见的模式是在描述类、方法和函数定义时使用第三人称，在注释代码片段、函数调用等时使用命令式语气

因此，当您在函数定义顶部有注释时，您就是在描述函数的功能。所以你用“创建foo”而不是“创建foo”

然后，如果需要描述函数调用，请使用祈使语气

// Create a Foo object
create_foo();

---

问错地方了。注释不应是对代码的重新表述。有整本书都致力于代码的可读性。如果你需要在行级别对代码的意图进行注释，而不是机器代码，那么你会遇到比动词时态更多的问题！我个人的经验是，那些采取疯狂评论做法的人，从来不会保留评论。…@BasileStarynkevitch：为了提高这个问题的抽象性和可读性，我将示例保持简单。我不会像这里那样假设对代码进行重新表述的注释，而是深入讨论。哪里是合适的提问地点？；我没有看到StackExchange fitting的英语论坛，因为我认为这个问题与编码有很大关系。有很多关于编码风格的问题。更具体一点，我100%不同意这个答案。第二种形式更简洁，也更容易理解。另外，当你在编程时，你实际上是在给计算机指令，对我来说，注释也反映了这一点。@RicardoSanchez Saez但文档是关于代码本身的文本，而不是用自然语言重新排列代码。至少在我看来，docstring应该回答开发人员在查看代码时遇到的第一个问题：“这是做什么的？”谢谢。这正是我想要的答案！问题是关于单行代码，而不是函数。在Java中，Javadoc字符串不附加到单行代码上，问题是关于单行代码，而不是函数。在Python中，docstring不附加到单行代码。

// Create a Foo object
create_foo();