一人称コメントは気を散らし、プロフェッショナルではありませんか？

私は自分が書いていた（古風なVisual Basic 6.0）コードで次のコメントを書いていることに気付いた。

If WindowState <> 1 Then
    'The form's not minimized, so we can resize it safely
    '...
End if

コメントで「私たち」を無意識のうちに使用する理由がわかりません。誰かがコードをステップスルーするのを想像しているのではないかと思っています。まるでそれらが実際に発生するのを見るのではなく、実際に各行のすべてのコマンドを「行っている」かのようです。この考え方では、私はI can resize it現在、それを「やっている」ので、またはyou can resize it、「将来」それをやっている人と話しているかのように使用できますが、これらのケースの両方は私は自分のコードを他の人に導くかのように「私たち」を使用します。

私は単純にそれを書き換えてit can be resized問題を回避できますが、それは私の好奇心を引き起こしました：コメントでこのような最初の人を使用することは一般的ですか、それとも気が散るおよび/または専門家でないと考えられますか？

コメントは、人間が理解するために書かれるべきです。人間がコミュニケーションをとるとき、通常は「I」、「We」、「you」などを使用します。

誰かがコードを理解しようとするとき、2人以上のアクターがいます。それを読む人と、コードの元の作者です。「私たち」と言っても結構です。「プロ」以外の場合は、「ロボットのような」という意味です。

コードのすべての責任を自動的に引き受けるため、「I」の使用を避けることをお勧めします。他の人がそれを読んでいる場合、それはこの場合のチームの努力であることを意図しているため、見た目が悪いでしょう。私たちは「私たち」の使用に無関心です。しかし、それは他の読者を不本意ながら含んでいるように見えるかもしれません。

私の投票は、簡潔さと簡潔さを求めています。メッセージをより冗長な方法で伝えることができる場合、なぜ他のものを選択するのですか？したがって、この例に関しては、次のように書きます。

'The form is not minimized so it can be resized safely.

私は2つのアプローチのうちの1つを取ります。通常は、より良いと思うものなら何でも。

要件や正当化のようなものを説明する際に、私たちはあなたがそこにいるように「私たち」と行きます：

// We can't proceed unless the user has given us this information.

プロセスを説明している場合は、命令的な（コマンド）音声を使用する傾向があります（それが間違った用語である場合は修正してください）。

// Get the foo from bar and make sure it follows our required format.

後者はコードを繰り返すことに危険なほど近づくことができますが、用途があります。ですから、私も私たちも使用していませんが、実際には「あなた」を意味しています。

私はそれが学術的/技術的な執筆スタイルの単なるバリエーションであり、多くの場合非人格的だと思います。パッシブボイスを使用し、「ロイヤルウィ」を使用します（「1」は古いのです）。

原則として、とにかく誰がそれを使用するかは非特定です-コメントは通常、元の著者だけでなく、メンテナーの利益のためです。

とは言うものの、私はコメントで最初の人をよく使用します- 特定の決定を下した理由と私が考えていたことを説明するために。

コメントは、何が行われているのかではなく、なぜ何が行われているのかを示す必要があります。実行されていることがコードから明らかでない場合は、コードを修正し、コメントを追加しないでください。一人称、二人称などは関係ありません。重要なのは必要な情報を伝えることです。

コードをナレーションする必要がある場合は、命令を好む、例えば

'ensure that the window is not minimized
If WindowState <> 1 Then
    'resize the window
    '...
End if

（そして、コードで「1」のような裸の定数を使用しないでください）

たぶん、私たちは魔法を起こさせるプログラムの中の小さな人たちに言及していますか？:)

英語の受動態は使いにくく、悪い音です。人々は個人フォーム（私、あなた、私たち、1つ）を使用するのが好きです。

例：

（あなた/私たち/一人）デリゲートを使用してウィンドウサイズ変更イベントを親に渡す

ウィンドウサイズ変更イベントを親に渡すためにデリゲートを使用する必要があります

別の例（コメント内の個人フォームをしばしば省略できることに注意してください）：

（私たち）例外をキャッチしました。（これから）エラーダイアログを表示します。

例外がキャッチされ、エラーダイアログが表示されます。

PS。パッシブを「あなた」に置き換えることは英語では非常に一般的であるため、他の言語にも漏れ始めています。たとえば、二人称単数形が存在するフィンランド語（英語の "thou"など）では、とてもおかしく聞こえます。

プログラムの実行について話している場合、それは「私たち」、「あなた」、「私」ではありません。擬人化は目立たないほど広まっているかもしれませんが、危険な習慣です（PDF警告。ダイクストラ警告。）：

擬人化は何よりも悪いと思います。私は今、「物事をしようとしている」、「物事をしたい」、「物事を真実であると信じている」、「物事を知っている」などのプログラムを見てきました。それはプログラマーにプログラムの実行で自分自身を識別するように促し、彼に操作上のセマンティクスの使用をほぼ強制します。

私は一人称や「ロイヤル・ウィー」のどちらかがプロではない、または気を散らすとは思わない。私は、「to be」動詞を持たない英語のサブセットであるE-Primeで英語のコメントを書く努力をすべきだと思います。

コメントで「to be」を使いすぎると、次のような紛らわしいステートメントが表示されます。

// X is 10
// X is the user data of the newly-authenticated user
// X is a BigInt

まあ、一度にすべてではないかもしれませんが、平等は本当にコメントを不明瞭にする可能性があります。

E-Primeで要件を書くことは、それらの要件を明確にするのに役立つと思います。作家はアクションとともに俳優を示さなければならないからです。

コメントの正しいスタイルは、非人格的な第三者です。「フォームは最小化されていないため、安全にサイズを変更できます。」

• 私は素朴です。
• あなたはひどいです。
• 私たちはフォーマルすぎる（そしてロイヤル）。

すべての文はこの方法で言い換えることができ（上記参照）、それが唯一の専門的な書き方です。

コメントに依存します。

通常、私は「The Mouth of a Cow」によって提案された方法でコメントを書きます。また、私は常にこの方法でドキュメント生成コメント（Doxygen、JavaDoc）を書いています。

ただし、多くの場合、バージョン管理を使用して、ソースファイル内の誰が行を書いた/触れたのかを特定しません。「I」と言うのが適切な場合があります。特に、コードを書いた人に「I」を追跡するのがかなり簡単な場合です。個人として決定を下した場合、「バージョン管理とともに」「I」を使用して、コードに沿って決定を識別および追跡することをお勧めします。

私の古き良き父（mhrip）は、「あなたが気にするより重要なことはありませんか？」と尋ねるでしょう。

しかし、個人的には、「私たち」が好きです。また、私が自分の会社で唯一の従業員であることを考えると、コードではなく、上流の文書で私たちを書く理由を疑問に思います。

しかし、私自身と私はこのように孤独を感じないことに同意します:)

「私たち」を書いて「私とコンピューター」（または「私のチームとコンピューター」）を考えるのは私だけですか？「私たち」は、外部から与えられたリクエストを処理します。つまり、「私たち」は、「私たち」のビジネス要件に基づいて、リクエストを読み取り、ウィンドウを開き、計算を行う必要があります。これは、コードを敵ではなくあなたの側の一部として見るのにも役立ちます:-)

短いコメントについては、次の開発者にコメントを読むように指示するメッセージのように、誰かに指示しているように、二人称で書くこともあります。といった

//You can get a session_id from SYSSession.getSessionID() if you need one

長いコメント（長い関数ヘッダーやアルゴリズムの説明の複数の行など）私は中立を保ち、一人称、二人称、三人称を残さないようにしています。

コードが十分に明確ではなかったため、このコメントを追加しました。一般的に、明確に定義された方法で意図を表現すると、コメントの使用が避けられます。たとえば、その行をという名前のメソッドに移動することもできますCanThisFormBeResized。

どんなに小さくても、名前の付いたメソッドはコメントに勝ちます。コメントとコードが簡単に同期しなくなるからです。

したがって、ほとんどのコメントをコードで表現できる場合、コメントの理由はほとんど残りません。

• あなたのコメントがあなたの意見である場合、「私」で始まります
• コメントを共有する意見（ベストプラクティスなど）であるとお考えの場合は、「私たち」から始めてください
• コメントが半信奉者によって書かれた危険なコードに向けられている場合は、コメントを破棄して、同僚からの紛らわしいコードを読み、それらに向かい合って対処します。

経験則として、最初の人、つまりを使用することをお勧めしますI。

どうして？私の所有的な性質のためではなく、人々が他の視点で話すとき、彼らはあまりに多くの単語を使うか、文章を複雑にしすぎて、物事を説明しようとして迷子になる傾向があるからです。最初の人は常に読みやすい傾向があります。

個人的に私は（C＃で）書くでしょう：

if (WindowState != WindowState.Minimised)
{
     ResizeWindowSafely();
}

またはそれらの線に沿って何か、したがってコメントを必要としません。