代码文档中的“我”，“我们”或都不

41

我发现自己（希望）在以下类型的代码（C ++）文档中写了有用的注释：

The reason we are doing this is...

之所以使用“我们”而不是“我”，是因为我经常在学术论文中经常偏爱“我们”。

所以这是问题。在编写代码时是否有充分的理由比另一个更好：

使用“我们”：我们这样做的原因是...
使用“我”：我这样做的原因是...
请使用我的名字：这样[my name]做的原因是...
被动语态：这样做的原因是...
都不：这样做是因为...

我之所以选择＃1，是因为我习惯于以这种方式编写，但是文档不是针对作者的，而是针对读者的，所以我想知道添加开发人员名称是否有帮助，或者是否只是添加了另一件事需要在维护代码时进行更改。

documentation

— 艾伦·图灵
source

我认为这取决于个人喜好。我看不出有什么理由能使一个总体上比另一个更清晰。

— ConditionRacer

6

＃5怎么样：“在人类事件过程中……”；）

— 蜡笔小新（

8

“四分七秒前，我们的祖先确实了解到，必须禁止foo，否则我们的部队必须被NULL克服”

— Philip

与English紧密相关：SE：为什么程序员在真正表示“我”或“您”时总是使用“我们”？（不幸的是，这是封闭的）

— 伊兹卡塔2013年

2

为什么不说This code was written like this because...？（被动语态）

— Alvin Wong

77

我会去：

＃6。声明式： ...

与其说“这样做的原因是因为每个Foo必须有一个酒吧”，不如说“每个Foo必须有一个酒吧”。使评论成为对原因的主动陈述，而不是被动的陈述。总体而言，这是一种更好的写作风格，更适合代码的本质（可以执行某些操作），并且该the reason this was done短语不会增加任何信息。它还可以完全避免您遇到的问题。

— 鲍勃森
source

您介意详细说明为什么要这么做吗？没有答案，这个答案看起来更像是一个简单的意见，与备份指南有些矛盾：'...意见并非全都不好，只要它得到了“我是专家”之外的支持。，或“因为我这么说”或“仅因为”。如上所述，请使用您的特定经验来支持您的观点，或指向您在网络或其他地方所做的一些研究，这些研究可提供证据来支持您的主张...”

— t 2013年

15

@gnat“这样做的原因”并没有在解释中添加任何内容。注释应该只包含足够的文字来说明要点，而不能包含更多内容。忽略细节，序言和其他填充文字。

— David Harkness

@gnat-当我看到您的评论时，我实际上刚刚添加了更多内容。

— Bobson

1

我认为我的示例过于简单，因为确实“这样做的原因”并没有增加任何内容。但是在某些情况下，棘手的情况需要一些解释，在这种情况下，我发现使用“我们”或“我”更自然，就像我在此评论中多次使用“我”一样。但是我认为您的回答在本质上是明确的：“声明性”建议：使用最少的词就能清楚地理解要点。

— 艾伦·图灵

7

在大多数情况下，我读//为because。

— Ilmo Euro

23

我都不喜欢，实际上完全不使用该介绍性短语，而是直截了当。我也尽量避免只说“ this”，因为它无法告知注释是否与代码同步。换句话说，代替：

// The reason this was done is to prevent null pointer exceptions later on.

我会说：

// Frobnicate the widget first so foo can never be null.

您实际上添加评论的事实意味着您在说出原因，因此您无需多余地告诉别人您在解释原因。请尽可能明确地说明原因，以便他们尽可能清楚地知道以后如何维护该代码。

— 卡尔·比勒费尔特
source

4

在C＃（以及大多数其他语言的文档工具）中，文档和嵌入式注释之间存在区别。我个人的观点是，您应该始终使用Bobson和其他人在类或成员的文档中建议的形式化，声明式的注释，但是在代码内，不那么形式化没有什么错。实际上，有时候非正式的评论比正式的英文完整的解释更能有效地解释为什么做某件事。

我认为这是一个示例，可以说明这一点。

/// <summary>
/// Takes data from the remote client and stores it in the database.
/// </summary>
/// <param name="data">The data to store.</param>
public void StoreData(ComplexObject data)
{
    // Don't take candy from strangers
    ComplexObject safeData = SanitizeData(data);
    ...
}

— 聚苯乙烯
source

4

旁注：SanitizeData应返回SafeComplexObject。;）

— 乔恩·珀迪

我同意，但我更喜欢文字（而不是隐喻）注释，尤其是当可能有来自不同语言背景的开发人员时。

— John B. Lambe

2

另一个要考虑的想法是精心设计的单元测试，该单元测试说明了为什么代码按其工作方式代替编写描述性注释的方式。与编写评论相比，这有很多好处：

更改代码后，注释并不总是会更改，这可能会在以后导致混乱。
单元测试使维护人员可以轻松地使用代码。如果您有单独的单元可以中断以观察变化，那么学习新的代码库会容易得多。

即使这种方法需要做更多的工作，单元测试还是一种很好的文档形式。

— 凡人
source

1

好的评论很难写，甚至最好的评论也常常很难阅读和理解。如果您的注释足够简洁，便于我理解，并且足够精确，足以传达我所需的代码知识，则使您使用的代词没有任何区别。

我不想劝阻别人评论他们的代码，因为他们担心代词的大小写，时态和人称。

— 约翰·M·甘特
source

让我澄清一下：对于将成为正式文档一部分的评论，更正式的说法是合适的，并且最好避免使用“我”和“我们”。我想到的这个答案是偶尔的解释性评论，例如，当您做了对下一个家伙来说看起来是错误的事情时。在那种情况下，只有在相同代码库中工作的人才能看到它，我说做任何事情都可以最清楚地传达您的意思，即使它是I wrote the code this way because...或what we really need here is...。在这些情况下，清晰的注释比严格的样式更重要。

— John M Gant 2013年

1

之所以使用“我们”而不是“我”，是因为我经常在学术论文中经常偏爱“我们”。

即使对于学术论文，这也是一种不好的风格，除非您试图隐藏谁真正决定了这一点。

至于您的具体问题：除非以以下内容开头，否则我不会留下这样的评论：

// TODO: clean this up, ...

或者除非它解释了非常重要的内容，否则从代码中可能并不清楚。在这种情况下，请使评论尽可能简短。

— BЈовић
source