coding-style - 2人目または3人目のコメント？

Question

2人目または3人目でコメントを書きますか？

// go somewhere and do something (2nd person comment)

また

// goes somewhere and does something (3rd person comment) 

Answer 1

私はしばしば医者のスタイルで話す傾向があります:

// Now we take $x and check whether it's valid for this pass

Answer 2

間違いなくサードパーソンスタイル。

Answer 3

1 つの役立つヒント: 各コメントはできるだけ自己完結型にするようにしてください。たとえば、次の形式です。

// First, mumble the frabbitz.

blah blah

// Second, foobar the quux

blah blah

これは素晴らしい物語ですが、「最初」と「2番目」の部分が正しくなくなる可能性があるため、コードの編集が難しくなります。結局、彼らはコメントにそれほど多くを追加することはありませんが、それらを脆弱な方法で相互に関連付けます.

Answer 4

私の見解では、最も快適に感じるスタイルを使用する必要があります。

埋め込まれたコメントは、コードの実装の詳細を理解しようとしているあなたや他の開発者が読むことを目的としています。明確でわかりやすいものである限り、文体が少し変わっていたり、文法が少しお粗末だったり、スペルミスがいくつかあったとしても問題はありません。これを読んでいる人は、そんなこと気にしないはずです。

API ドキュメントを形成するために抽出されたコメントは、スタイル、文法、スペルの細かな点にもう少し注意を払う必要があります。しかし、ここでも正確さと完全性がはるかに重要です。

Answer 5

一人称で話すこともあるけど、こうやって

/*
Usage:  
set_position(0.5, 0.5);  // im in the center
set_position(0.0, 1.0);  // im in the lower,left corner
*/

Answer 6

コードを編集している人数と目的によって異なります。私自身のコード (公開用ですが) では、おそらく「I」を使用して、個人的なコメントを自由に追加できます。共同プロジェクトでは、コメントは共同スタイルを目指している必要があり、「私」は場違いかもしれません。

コメントは脆弱であり、多くの最新の権威 (Clean Code など) は、関数とフィールドに意味のある名前を付ける必要があることを示唆していることに注意してください。しかし、もちろん、説明的なコメントがまだ不可欠な場所はたくさんあります。