「I」、「We」、またはコードドキュメントに含まれない

このタイプのコード（C ++）ドキュメントに役立つコメントを（できれば）書いていることに気付きました

The reason we are doing this is...

「私」の代わりに「私たち」を使用する理由は、「私たち」が好まれることが多い学術論文をたくさん書いているからです。

だからここに質問があります。コードを文書化する際に一方を他方に優先させる正当な理由はありますか？

1. 「私たち」を使用：これを行う理由は...
2. 「I」を使用：これを行う理由は...
3. 私の名前を使用してください：理由[my name]は...
4. 受動態：これが行われた理由は...
5. どちらでもない：これを行うのは...

私はその方法を書くのに慣れているので＃1を選択しますが、ドキュメントはライター向けではなく、読者向けです。コードを保守するときに変更されます。

私は一緒に行きます：

＃6。宣言的： ...

「これが行われた理由は、各Fooにはバーが必要だから」と言うのではなく、「各Fooにはバーが必要」と言うだけです。コメントを受動的なものではなく、理由の積極的な声明にします。これは、一般的に、全体的な、より良い文章のスタイル、より良いフィット（コードの性質だし、何かを）、およびthe reason this was doneフレーズは一切の情報を追加していません。また、発生している問題を正確に回避します。

私はどちらも好みません。実際、その導入フレーズを完全に省略して、要点を説明します。また、コメントがコードと同期しているかどうかを判断する方法がないため、「これ」とだけ言うのも避けようとします。つまり、次の代わりに：

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

私は言うだろう：

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

コメントを追加しているという事実は、理由を述べていることを意味しているので、理由を説明している人に重複して伝える必要はありません。理由をできるだけ具体的にするだけで、後でそのコードを維持する方法をできる限り明確に知ることができます。

C＃（および他の言語のほとんどのドキュメントツール）では、ドキュメントとインラインのコメントに違いがあります。私個人の意見では、ボブソンや他の人がクラスやメンバーのドキュメントで提案しているように、常に正式な宣言スタイルのコメントを使用する必要がありますが、コード内では、正式ではないことは問題ありません。実際には、時には非公式コメントがあるより多くの何かが正式な英語で完全な博覧会よりも、ドンされる理由を説明するのに効果的。

これがポイントを示すと思うサンプルです。

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

考慮すべきもう1つのアイデアは、記述的なコメントを書く代わりに、コードがそのように機能する理由を示す、巧妙に作成された単体テストです。これには、コメントを書くよりもいくつかの利点があります。

1. コードが変更されたときにコメントが常に変更されるとは限らないため、後で混乱する可能性があります。

2. ユニットテストにより、メンテナーはコードを簡単に操作できます。新しいコードベースを学ぶのは、個々のユニットを壊して、どのような変化を観察できるかがはるかに簡単です。

この方法は前もってより多くの作業を必要としますが、ユニットテストは優れた形式のドキュメントになります。

良いコメントは書くのが難しく、最高のコメントでさえ読むことも理解することも難しいことがよくあります。あなたのコメントが私にとって十分に簡潔で、コードについて知っておくべきことを伝えるのに十分なほど正確である場合、あなたが使用する代名詞に違いはありません。

代名詞の格、時制、人物について心配しているので、誰かがコードにコメントするのを思いとどまらせたいです。

「私」の代わりに「私たち」を使用する理由は、「私たち」が好まれることが多い学術論文をたくさん書いているからです。

あなたが実際にその正確なポイントを決定した人を隠そうとしない限り、それは学術論文にとってさえ悪いスタイルです。

あなたの特定の質問については、次で始まる場合を除き、このようなコメントは残しません。

// TODO: clean this up, ...

または、非常に重要なことを説明していない限り、コードからはそれほど明確ではないかもしれません。その場合は、コメントをできるだけ短くしてください。