我有一个关于编程和英语的问题：在评论单行代码时是使用第三人还是命令。 假设应该注释的命令式语言中的以下代码行：
object.doSomething();
我评论这一行的方法是将评论置于其后使用第三人称，这将是一个普通的英语句子，其中包含该行作为主题：
object.doSomething(); // does (referencing to the line of code) some action
但是，由于我们处于命令式语言中，因此实际上“命令”了计算机，人们甚至可以考虑将注释放在代码之前并使用命令：
//Do some action:
object.doSomething();
当需要评论彼此相关的多条线时，这甚至是有用的。
我个人更喜欢第一种风格，但我常常不确定使用什么样的风格。如果有些人可以在这里写下他们的个人经历，那将是很棒的。
答案 0 :(得分：15)
Oracle的官方风格指南指出：
使用第3人（描述性）而不是第2人（规定性）。 描述是第三人称声明，而不是第二人称。
获取标签。 （优选的）
获取标签。 （避免）
可以找到Oracle的样式指南here。
答案 1 :(得分：3)
Google有明确的指令，区分针对接口实现者的文档（说明操作方式，命令式风格）和针对库用户的文档（说明操作方式，第三人称风格），这就是您的情况
诚然，这种区别对于行级注释几乎没有意义，因为行级注释总是解释代码的作用。
换句话说，这对我来说是第三人称。
答案 2 :(得分：2)
第一种方法肯定是更合适的评论方法，因为人们在阅读您的评论时，重要的是它们尽可能易于阅读。 //Do something听起来像是在与计算机交谈，而不是解释代码的作用。
答案 3 :(得分：1)
对于Python，PEP-257声明有关文档字符串的信息（添加了强调）：
文档字符串是一个以句点结尾的短语。它规定了功能或 方法的效果作为命令（“执行此操作”，“返回该结果”），不作为描述； 例如不要写“返回路径名...”。
PEP257: Good Python docstring by example更明确（强调）：
请注意，所有文档字符串都以单行摘要开头。摘要是 以祈使语气（“做”，“使用”，“查找”，“返回”，“渲染”， 等等），并以句号结尾。
答案 4 :(得分：1)
我认为我见过的最常见的模式是在描述类、方法和函数定义时使用第三人称，在评论代码片段、函数调用等时使用命令式。
因此，当您在函数定义之上添加注释时，您就是在描述该函数的作用。所以你使用“Creates foo”而不是“Create foo”
// Creates a Foo object
function create_foo() {
// ...
}
然后，如果您需要描述一个函数调用，请使用命令式。
// Create a Foo object
create_foo();