评论风格:势在必行或第三人称

Question

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

object.doSomething();

我评论这一行的方法是使用第三人称这个评论背后的评论是一个普通的英语句子,包含作为主题的行:

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

但由于我们处于命令式语言中,因此实际上"命令"了计算机,人们甚至可以考虑将注释放在代码之前并使用命令:

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

当需要评论彼此相关的多条线时,这甚至是有用的.

我个人更喜欢第一种风格,但我常常不确定使用什么样的风格.如果有些人可以在这里写下他们的个人经历,那将是很棒的.

Answer 1

Oracle的官方风格指南指出:

使用第3人(描述性)而不是第2人(规定性).描述是第三人称声明,而不是第二人称.

获取标签.(优选的)

获得标签.(避免)

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

Answer 2

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

因此，当您在函数定义之上添加注释时，您就是在描述该函数的用途。所以你使用“Creates foo”而不是“Create foo”

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

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

// Create a Foo object
create_foo();

Answer 3

第一种方法绝对是更合适的评论方法，因为人们会阅读您的评论，重要的是他们尽可能容易阅读。//Do something听起来您是在与计算机交谈，而不是在解释代码的作用。

Answer 4

对于Python，PEP-257声明有关文档字符串的信息（添加了强调）：

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

请注意，所有文档字符串均以单行摘要开头。摘要以命令式语气（“执行”，“使用”，“查找”，“返回”，“呈现”等）编写，并以句号结尾。

Answer 5

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

诚然，这种区别对于行级注释来说意义不大，行级注释总是解释代码的作用。

换句话说，它对我来说是第三人称。