注释风格：命令式或第三人称

Question

我有一个关于编程和英语语言的问题：在注释单行代码时，是使用第三人称还是祈使语？ 假设以下是一个需要被注释的祈使语言的代码行：

object.doSomething();

我评论这行代码的方法是在它后面使用第三人称，就像这个句子把该行作为主语一样：

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

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

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

当需要注释多行代码时，这个功能尤其有用。

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

- Sebastian Hoffmann

---

不是提问的正确地方。注释不应该是代码的重新表述。有整本书专门讲解代码可读性。 - Basile Starynkevitch

如果你需要在代码行级别上评论代码意图，而它不是机器码，那么你的问题比动词时态还要多得多！我的个人经验是，实施疯狂的注释惯例的人从来不会维护这些注释... - Tony Hopkinson

@BasileStarynkevitch说：“我为了提高这个问题的抽象性和可读性而保持了例子的简单。我不认为评论应该像这里一样重新表达代码，而是应该详细说明。那么问这个问题的正确地方在哪里？我觉得StackExchange的英文论坛并不适合，因为我认为这个问题与编程密切相关。” - Sebastian Hoffmann

http://programmers.stackexchange.com/ 上有许多关于编码风格的问题。 - Darren Burgess

更具体地说，在他们的编码风格标签下搜索。 - Sz.

Answer 1

Oracle官方的样式指南规定：

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

获取标签。（推荐）

避免使用“获取您的标签”等表述。（避免）

Oracle的样式指南可以在这里找到。

- Robin Nabel

---

谢谢。这正是我在寻找的答案类型！ - Nicolas Garnier

问题是关于单行代码，而不是函数。在Java中，Javadoc字符串不附加到单行代码。 - Bruno Haible

Answer 2

对于Python，PEP-257关于文档字符串（重点添加）的规定如下：

文档字符串是以句号结尾的短语。它作为函数或方法的效果的命令（“执行此操作”，“返回那个”），而不是作为描述。例如，不要写“返回路径名...”。

而PEP257: Good Python docstring by example更加明确（重点添加）：

注意，所有文档字符串都以一行摘要开头。 摘要采用祈使语气（“做”，“使用”，“查找”，“返回”，“渲染”等）并以句号结束。

- wstomv

---

问题是关于_单行代码_，而不是函数。在Python中，文档字符串并没有与单行代码相关联。 - Bruno Haible

Answer 3

谷歌有明确的指导方针，区分面向接口实现者的文档（解释如何做，命令式风格）和面向库用户的文档（解释其功能，第三人称风格），而您的情况属于后者。可以承认的是，对于行级注释，这种区分几乎没有意义，因为它们总是解释代码的功能。换句话说，对我来说是第三人称。

https://developers.google.com/style/reference-verbs

- Vicne

Answer 4

第一种方法显然是更适合的评论方式，因为读取您的评论的人很重要，所以它们应尽可能易于阅读。 //做某事 听起来像你在和计算机交流而不是解释代码的功能。

- Darren Burgess

---

我完全不同意这个答案。第二种形式更加简洁，同样易于理解。而且，当你在编程时，确实是在给计算机提供指令，对我来说，注释也反映了这一点。 - Ricardo Sanchez-Saez

@RicardoSanchez-Saez 但是文档是关于代码本身的文字，而不是对代码的自然语言重新排列。至少在我看来，docstring 应该回答开发人员在查看代码片段时的第一个问题：“这个代码是做什么的？” - user4052054

Answer 5

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

因此，当您在一个函数定义的顶部添加注释时，您正在描述该函数的功能。所以您应该使用"Creates foo"而不是"Create foo"。

// Creates a Foo object
function create_foo() {
// ...
}

如果你需要描述一个函数调用，那么请使用祈使语气。

// Create a Foo object
create_foo();

- Maciej Krawczyk

Answer 6

传统提交使用 祈使现在时

我应该使用什么写作形式？

我们建议使用祈使语现在时的写作形式来撰写提交描述和正文。

有很多这种写作形式的提交例子，如 1，2，3，4，5。

与上面的回答中 使用命令语气 的 Python 相似

- iki

---

这个问题与Git无关。 - Luis Hernandez