"I“、”我们“，或者在代码文档中都没有。

Question

我发现自己在代码(C++)类型的文档中写了一些有用的注释(希望如此)：

The reason we are doing this is...

我之所以使用“我们”而不是“我”，是因为我做了很多学术写作，而“我们”往往是首选的。

这就是问题所在。在编写代码时，是否有充分的理由选择其中一种而不是另一种：

1. 使用“我们”：我们这么做的原因是..。
2. 我这么做的原因是..。
3. 用我的名字：[my name]这么做的原因是..。
4. 被动语态:这样做的原因是..。
5. 两个人都不这么做因为..。

我选择#1是因为我习惯了这样写，但是文档不是为作者准备的，而是为读者准备的，所以我想知道添加开发人员名称是否有帮助，或者只是添加了另一个在维护代码时需要更改的内容。

Answer 1

我会选择：

#6.声明性：.

不要说“之所以这样做是因为每个Foo必须有一个Bar"，而只是说”每个Foo必须有一个Bar“。把评论变成积极的理由陈述，而不是被动的。总的来说，这是一种更好的写作风格，更符合代码的本质(它可以做一些事情)，而且the reason this was done短语没有添加任何信息。它也完全避免了你遇到的问题。

Answer 2

我既不喜欢，也不喜欢这个介绍性的短语，只想说重点。我还尽量避免只说“这个”，因为它无法判断注释是否与代码同步。换句话说，而不是：

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

我想说：

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

事实上，你添加了一条评论，这意味着你是在陈述一个理由，所以你不需要重复地告诉人们你在解释原因。只要尽可能具体地说明原因，他们就会尽可能清楚地知道以后如何维护该代码。

Answer 3

在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);
    ...
}