コードでコメントを作成するのが嫌いなチームメンバーに対処するにはどうすればよいですか？

私のチームメンバーの1人は、自分のコードでコメントを作成することを常に避けています。

彼のコードは自己文書化されておらず、他のプログラマーは彼のコードを理解するのに苦労しています。

私は彼に彼のコードをコメントするように何度も頼んだが、彼はただ言い訳をするか、または彼が後でそれをすることを主張する。彼の懸念は、コメントの追加に時間がかかりすぎてプロジェクトが遅れることです。

彼に彼のコードを適切に文書化するよう説得するために、どのような議論を彼に提示できますか？

そのメモでは、コードのコメントに焦点を当てるのは間違っていますか、これは対処すべき大きな問題を示していますか？

コメントだけではコードの改善にはなりません。「コメントを増やす」だけを押しても、/* increment i by 1 */スタイルコメント以上のものは得られないでしょう。

だから、なぜあなたはそれらのコメントが欲しいのか自問してください。「ベストプラクティス」は、理由を理解しない限り、引数としてカウントされません。

現在、コメントを使用する最も顕著な理由は、コードを理解しやすくすることであり、コメントの欠如について人々が不平を言うとき、彼らは無知なオウムであるか、作業しているコードを理解するのに苦労しています。

したがって、コメントの欠落について文句を言わないでください。判読できないコードについて文句を言います。あるいは、文句を言わずに、コードについて質問を続けるだけです。あなたが理解できないことについては、それを書いた人に尋ねてください。とにかくそうするべきです。コードが読めない場合は、さらに質問をするだけです。また、後でコードに戻って、それが何をするのか正確に覚えていない場合は、同じ質問をもう一度尋ねてください。

コメントで修正でき、同僚の頭脳が機能している場合、彼/彼女はいつかコードにコメントする方が、いつも愚かな質問をするよりずっと簡単だと気づくでしょう。そして、質問を思い付かない場合は、そのコードはすでに完全に読み取り可能であり、すべてのコードにコメントが必要というわけではありません。

人々のスキルの面では、犠牲を払ったり、非難したりすることは一切避けてください。あなたの質問について真面目で正直になってください。

自己文書化コードや役に立つコメントを書くのに苦労した多くの開発者に会いました。これらの種類の人々は、しばしばそれを正しく行うのに十分な自己規律や経験を欠いています。

うまくいかないのは、「コメントを追加するように伝えて」です。これは彼らの自制心も経験も増しません。私見で唯一機能するのは、コードレビューとリファクタリングセッションを頻繁に行うことです。開発者がタスクを完了したら、開発者が理解できないコードの部分を説明できるようにします。すぐにリファクタリングまたはドキュメント化して、6か月後に両方が理解できるようにします。

これを数か月間、少なくとも週に2回行います。運がよければ、他の開発者はこれらのセッションを通じて学習するため、レビューの頻度を減らすことができます。

誰もまだコードレビューについて言及していないことに驚いています。コードレビューを行う！彼が質の悪いチェックインをしているときは、「コメントを追加する」だけで言ってはいけません。絶えず質問をして、彼のコードが何をするのか、何故なのかを彼に話させてください。メモする。次に、コードレビューの最後に、メモのコピーを彼に渡し、質問をかなり明確にするように伝えます。コメントを増やすか、コードをリファクタリングして品質を向上させます（可能な場合は後者が望ましい）

これは、チームワーカーが生成するコードによって異なります。Uncle BobからClean Codeの本を読むと、彼は実際にはコードにコメントを追加しない方が好きであることがわかります。コード自体が本来あるべきほど読みやすい場合、コメントはほとんど必要ありません。

そうでない場合、または交渉不可能なポリシーのためにコメントが必要な場合、主な質問は、彼/彼女にコメントを書いて欲しいのはあなただけなのか、それともチーム全体かチーム/プロジェクトなのか盟主。自分だけの場合は、他の同僚と話して、なぜそれほど大したことではないのかを調べる必要があります。

プロジェクトリーダーにコメントがない場合は、完全性の一部としてコメントを要求することもできます。つまり、送信されたコードにコメントがない場合、作業はまだ完了していません。彼は、現在の作業が終了し、そのためにコメントが必要になるまで、他の作業を続けることはできません。ただし、この種の強制は恐らく恐ろしいコメントになる可能性が最も高いことを覚えておいてください（コードコメントのくだらない繰り返しが予想されます）。

私の謙虚な意見で唯一可能な方法は、あなたと他のみんながコメントから得る実際の利益について議論することです。単に議論するだけでは理解できない場合は、常に難しい方法もあります。新しいコードを記述させるのではなく、既存のコードで動作させるようにします。可能であれば、2つの異なる作業領域を見つける必要があります。1つは適切に役立つコメントがあり、もう1つはコメントがありません。他の誰かの読めない、コメントされていないコードを読まなければならないことは、あなた自身の仕事に関して驚くべきことです。

私たちは皆、一度そこに行ったことがありますので、あるソースの元の作者がとてもずさんな仕事をしていることに怒っていました。私たち一人ひとりが読みやすさを気にする必要があることを実感させるのは、私たち一人一人が同様に著者であるという追加の反省です。

指示に従うことができない従業員がいる場合、彼をre責し、それが彼のキャリアの向上に役立たないことを明確にしてください。コーディングスタイルの一貫性はチームにとって重要です。他の全員がコメントを書いていて、これがそうでない場合、コーディングスタイルが損なわれます。

とはいえ、おそらくあなたは彼を助けることができます。私の経験では、コメントに時間がかかりすぎると誰かが抗議すると、次のような心理的障壁があります。

1. 彼は自分のコード/デザインの選択について自意識があり、それらを散文でレイアウトしたくありません。（コードレビューは、誰かの自信を取り戻すだけでなく、自信を高めるのにも役立ちます。）
2. 彼は非常に直線的に働いており、あまり先を見ていません。別の方法で意図を構成するために、彼が作業メモリーから書き込もうとしていた即時コードをアンロードせざるを得ないため、コメントは苦痛です。（これが当てはまる場合、コメントはコードの品質にとって非常に重要になります。）
3. 歴史的に人々は彼のコメントを理解していません。

プログラマーは、コメントがテストのようなものであることを理解することが重要です。コメントは将来の使用のためだけではなく、プログラマー自身のためでもあります。彼らは彼に彼のアプローチについて違った考え方を強いる。

これはいずれも、CI、テスト、またはコードレビューに代わるものではありません。それは、コーディングの多くの重要な部分の1つにすぎず、それ自体はコードを記述しません。

コードレビューソフトウェアを入手して、それをうまく利用してください。

私たちはKiを使用し、それが大好きです。すべてのチェンジセットをレビューする必要があるというポリシーがあります（開発者はタグと競合のないマージで自分自身のレビューを提起/承認できますが（ほとんどの人はrebaseifを使用しますが）、この方法でレビューなしでチェンジセットをすばやく見つけることができます）。

明確でないコードは、コードレビューが拒否される理由です。修正がコメントであるか、より明確なコードであるかは関係ありませんが、レビュー担当者はそれを理解できる必要があります。一部の開発者はコードの書き直しを好みますが、他の開発者（自分自身を含む）はしばしばコメントで意図を表現する方が簡単だと感じます（コードはそれが何をするかを簡単に示すことができますが、何をすべきかを示すのは難しいです）。

コードの明快さについて疑問がある場合は、常にレビュアーが勝ちます。もちろん、著者はそれを書いたので理解しています。他の人に明確にする必要があります。

Kilnのようなソフトウェアを使用すると、変更セットが見落とされることはありません。私の開発チームの誰もがこの方法を好みます。コードレビューソフトウェアは、コードの品質とアプリケーションの品質の両方に大きな影響を与えました:-)

開発者は、最初にソフトウェアを導入するときに拒否されたレビューで防御するのは簡単ですが、私の経験では、物事がこのように優れていることを認識し、それを受け入れるのに長い時間はかかりません:-)

編集：また、注目に値する、私たちは開発者に口頭で、またはレビューのコメントで不可解なコードを説明させないようにします。不明な点がある場合は、コード内（コメントまたはリファクタリング）で説明し、新しいレビューセットを同じレビューに追加してください。

興味深いことに、自然言語に適用される読みやすさは、読みと理解の速度によって測定されます。特定のコードコメントがこのプロパティを改善しない場合、単純なルールを実際に採用できると思いますが、回避できます。

コメントする理由

コードコメントは埋め込みドキュメントの一種ですが、ハイエンドプログラミング言語には、言語自体の要素を使用して（意味のあるコードの）余分な「過剰なドキュメント化」プログラミングを回避する方法がいくつかあります。また、コードをプログラミング教科書のリストに変換するのも悪い考えです。個々のステートメントは、ほぼトートロジー的な方法で文字通り説明されます（既に提供された回答の「/ * increment i by 1 * /」の例）言語に不慣れなプログラマーのみに。

それにもかかわらず、それは本当に「すべての悪の源」である「文書化されていない」（しかし意味のない）コードにコメントしようとする意図です。「十分に文書化されていない」コードの存在そのものは悪いシグナルです。それは、構造化されていない混乱であるか、神秘的な失われた目的の奇抜なハックです。明らかに、そのようなコードの価値には少なくとも疑問があります。残念ながら、例は常にあります。（視覚的にグループ化された）コード化されたコードのセクションにコメントを導入するほうが、新しいサブルーチンにラップするよりも良い場合（「愚かな一貫性」という「小さな心のホブゴブリン」） 。

コードの読みやすさ！=コードのコメント

読み取り可能なコードでは、コメントによる注釈は必要ありません。コード内の各特定の場所には、この特定のコードが達成することになっているタスクのコンテキストが常にあります。目的が欠けていたり、コードが何か不思議なことをしたりする場合は、それを避けてください。奇妙なハッキングによるコードの入力を許可しないでください。これは、バグのあるテクノロジーと基礎を理解するための時間/関心の欠如を組み合わせた直接的な結果です。プロジェクトで神秘的なコードを避けてください！

一方、Readable program = code + documentationには、たとえば「APIへのコメント」ドキュメントの生成を容易にするために、複数の正当なコメントのセクションを含めることができます。

コードスタイルの標準に従う

おもしろいことに、質問はコードをコメントする理由ではなく、チーム作業- 高度に同期されたスタイルでコードを生成する方法（他のすべての人が読む/理解できる）についてです。会社でコードスタイルの標準に従っていますか？主な目的は、リファクタリングを必要とする、あまりにも「個人的」かつ「主観的に」あいまいなコードの記述を避けることです。だから、コードスタイルを使用する必要があると思うなら、それを適切に実装する方法の完全なツールがあります-人の教育から始まり、コードの品質管理（多数のリントなど）と（改訂コントロール統合）コードレビューシステム。

コードを読みやすくするエバンジェリストになる

コードが書かれているよりも頻繁に読み取られることに同意する場合。コミュニケーションに使用される言語（数学、マシンコード、または旧英語）に関係なく、アイデアと思考を明確に表現することが重要である場合..あなたの使命が、鈍くい代替思考を根絶することである場合。（申し訳ありません、最後は別の「マニフェスト」からです）..質問をし、議論を開始し、コードクリーニングに関する考えを喚起する本を広め始めます（おそらく、Beckのデザインパターンに似たものだけでなく、RC Martinによって既に言及されているようなもの）。プログラミングで。さらに重要なアイデアの箇条書きの文章を読みます（読みやすさに関するO'Reillyの本から引用）

• コードのすべての行に適用されるヒントを使用して、命名、コメント、フォーマットを簡素化します
• プログラムのループ、ロジック、変数を調整して、複雑さと混乱を減らします
• 一度に1つのタスクを実行するようにコードブロックを再編成するなど、機能レベルでの攻撃の問題
• 徹底的かつ簡潔で、読みやすい効果的なテストコードを書く

「コメント」を切り取り、まだたくさん残っています（コメントを必要としないコードを書くことは、すばらしい練習の1つです！）。意味的に意味のある識別子に名前を付けることは良い出発点です。次に、論理的に接続された操作を関数とクラスにグループ化して、コードを構造化します。等々。優れたプログラマーは、優れたライターです（もちろん、他の技術スキルがあれば）。

コードのコメントに集中するのは間違っていますか、これは対処すべき大きな問題を示していますか？

幾分。優れたコードにはコメントは不要です。しかし、あなたが言ったように、彼のコードは自己文書化されていません。だから私はコメントに集中しません。開発者のスキルとクラフツマンシップの向上に集中する必要があります。

それでそれを行う方法は？レビュー/リファクタリングセッションに関するDoc Brownの提案は、良いアイデアです。ペアプログラミングはさらに効果的ですが、実装するのがかなり難しい場合もあります。

まず第一に、コメントについてのあなたのアプローチに再対処することをお勧めします。

APIレベルのドキュメンテーションコメント（後で公開される）である場合、この開発者は単に仕事をしていません。しかし、他のすべてのコメントについては、注意してください。

私がそれらに遭遇するほとんどの場合、コメントは悪です。ロバート・マーティンによる「クリーンコード」のコードコメントの章を読んで、その理由をよく理解することをお勧めします。

コメントはいくつかの点でコードを傷つけます：

1）メンテナンスが難しい。リファクタリングするとき、余分な作業をする必要があります。コメントに記述されているロジックを変更する場合は、コメントも編集する必要があります。

2）彼らはしばしば嘘をつきます。コメントを信用することはできず、代わりにコードを読む必要があります。どちらが質問を提起します：なぜあなたはまったくコメントが必要なのでしょうか？

// this method returns the sum of 'a' and 'b'
public int GetHash(int a, int b)
{
    //the calculation of the hash
    int result = a*b;
}

（ハッシュは合計ではなく積です。）

3）コメントはコードを乱雑にし、非常にまれに値を追加します。

私の解決策：コメントを追加する代わりに、それらをすべて削除するようにしてください！

チームメンバーが別のチームメンバーのコードを理解できない場合（何らかの理由で）。次に、そのチームメンバーは、元のコード（正解なリビジョン管理システム）を書いた人を見つけることができ、コードの作成者に直接説明するように奨励する必要があります（たとえば、机に向かって歩き、座り、話し合います）。

この場合、コメントの欠如が問題である場合、コードに適切にコメントしていない人は、自分が行ったことを説明するのに多くの時間を費やします。そして（もし彼らが賢いなら）それらすべての説明に時間を費やさないようにコメントを追加し始めます。

チームメンバーが説明を求め合うように促すことは、他の理由で価値があることに注意してください。たとえば、チームメンバーの経験が少なく、経験豊富なチームメンバーから物事を学ぶことができます。

ほとんどの場合、チームメンバーが説明を求め合うように奨励することで、自己均衡システムを作成します。異なるチームメンバーが互いに「自動調整」する場所。

これは、主にtdammersの回答の拡張ですが、定期的にコードレビューを実行します。

彼（および他の開発者）に座ってコードを見てもらい、上司や同僚の前で多かれ少なかれ防御することで、誰もがより優れたコーダーを作り、比較的短期間で真の価値を高めます。短期的には、問題の開発者に、レビュー時に自分のコードを適切にコメントする口実を与えません。

編集：私が誰かが私の提案に反対票を投じる理由については確信がありません-コードレビューの利点は一般的な知識であることを当然と思っていました...実践のコミュニティ分析についてはこのスレッドをご覧ください：

コードレビューは良い習慣ですか？

コメントに関してしばしば極端な意見を考慮して、私は中に入るのをためらいます。

あなたが（読めない）コードを書くつもりなら、それを適切に文書化すべきだと私が提示できるいくつかの議論は何ですか？

保守可能で読みやすいコードの書き方を理解するには、時間、実践、経験が必要です。経験の浅いプログラマー（そして悲しいことに多くの経験豊富なプログラマー）は、しばしばイケア効果（PDF）に苦しんでいます。それは彼らがそれを構築し、親密にそれをよく知っているからであり、彼らはコードが素晴らしいだけでなく、読みやすいと確信しているからです。

その人が優れたプログラマーである場合、ドキュメントはほとんど必要ありません。ただし、ほとんどのプログラマーは素晴らしくなく、多くのコードが「読み取り可能性」部門で苦しむことになります。平凡なプログラマーまたは開発中のプログラマーに「コードを説明する」ように依頼することは、より批判的な目でコードを見るように強制するので便利です。

これは、コードを「文書化する」ことを意味しますか？必ずしも。適切な例として、過去にこの問題を抱えた同様のプログラマーがいました。私は彼に文書を強制しました。残念ながら、彼のドキュメントは彼のコードと同様に判読できず、何も追加しませんでした。振り返ってみると、コードレビューの方が役立つでしょう。

あなた（またはデリゲート）は、このプログラマーと一緒に座って、彼の古いコードの一部を取得する必要があります。彼がそれに取り組んでいるだけで知っている新しいものではありません。最小限の操作で彼のコードを説明するように彼に依頼する必要があります。これは、別の「文書化」セッションでもあり、そこで彼は自分のコードを書く際に説明します。その後、彼はより良いアプローチに関するフィードバックを得る必要があります。

余談ですが、コードの "読みやすさ"がどれほど優れていても、いくつかのドキュメントが必要になることがあります。APIにはドキュメントが必要で、非常に技術的で複雑な操作にはプログラマーが関与するプロセスを理解するのに役立つドキュメントが必要です（多くの場合、プログラマーの知識の範囲外）。

多くのプロジェクトでは、コードド​​キュメントが必要です：インターフェイスドキュメント、デザインドキュメント、...

一部のプロジェクトでは、コードとドキュメントの一貫性を保つために、そのようなドキュメントをコードコメントに入れ、Doxygen、Sphinx、Javadocなどのツールで抽出する必要があります。

そのようにして、開発者は有用なコメントをコードで記述する必要があり、この義務はプロジェクト計画に統合されます。

答えとコメントのほとんどが示唆していることを述べます：おそらく、あなたが認識した解決策を押し通そうとするのではなく、ここで本当の問題を理解する必要があるでしょう。

あなたは彼のコードにコメントを見たいと思っています。なんで？理由を挙げました。その理由がなぜあなたにとってそれほど重要なのですか？彼は代わりに何か他のことをやる気があります。なんで？彼は理由を述べます。なぜその理由が彼にとってそれほど重要なのでしょうか？競合が実際に発生するレベルに到達するまでこれを繰り返し、両方の人と一緒に暮らせる解決策を見つけようとします。コメントとはほとんど関係がないと思います。

適切なコーディング標準に従う場合、最低限必要なコメントがあります。命名規則は重要です。メソッド名と変数名は、それらの役割を記述する必要があります。

私のTLは、コメントを少なくすることを勧めています。彼は私のコードが理解可能で自己記述的であることを望んでいます。簡単な例：検索パターンに使用される文字列型の変数名

   var str1:String="" //not uderstandable
   var strSearchPattern:String="" //uderstandable

コードレビューの回答が大好きですが、おそらく私のプロセスも少し役立つでしょう。

私はコメントが大好きですが、最初のパスでコードにコメントを追加することはほとんどありません。たぶんそれは私のスタイルだけかもしれませんが、開発中に同じセクションのコードを3〜5回ヒットします（リファクタリング、テストの作成など）。

少し混乱したとき、または誰かがコードのセクションについて質問するたびに、それが意味をなすように修正しようとします。

これは、コメントを追加するだけで複雑な操作セットを独自の関数に削除したり、新しいオブジェクトの抽出などのより大きなリファクタリングをトリガーしたりできます。

グループの全員に、自分のコードが他の人に読めるように「所有」することをお勧めします。つまり、誰かがあなたのコードについて質問するたびに、変更を加えることを約束します。すぐに変更を加える人！

「チーム契約」の一部としてこれをプッシュすることを真剣に検討してください（契約がない場合は、契約を明確に作成してください）。あなたが何をすることに同意したかについての質問。

たぶん、この男には、優れたコーディングの規律と、他の人が自分が書いたコードを理解できることが重要であるということを評価する必要があります。

私は自分のキャリアの中で本当にひどいコードベースに取り組んできました。コードベースがひどく整理されていて、変数名がひどく貧弱で、コメントがひどくまたは存在しないため、コードベースは私の生産性を損ないました。理解できないコードベースを修正したり改善したりすることはできません。また、初心者が理解できない方法で記述されている場合、実際に作業するよりも理解しようとする時間が長くなります。

厳しい経験ほど優れた教師はいません！

すべてのコードベースにはいくつかの恐ろしいビットが潜んでおり、何かを壊すことを恐れているために誰も触れたくないシステムの部分、またはコードを書いた人が長く離れて理解を深めたために意味のある作業を行うことができませんそれらのコードの。そのコードがコメント化されておらず、自己文書化されていない場合、事態はさらに悪化します。

そのようなコードベースを見つけて、面倒なコーダーに責任を負わせることをお勧めします。彼にそれの所有権を与え、彼の責任を負わせ、文書化されていないか短期間で理解することが不可能であるために維持できないコードに取り組むことの本当の苦痛を彼に学ばせてください。それに数ヶ月取り組んだ後、彼がやってくると確信しています。

彼にコメントなしで別のコードを渡して、コードを理解するように頼みます。彼は適切なコメントの重要性を理解しているかもしれません。

このプログラマはコードのメンテナンスを行いますか？そうでない場合、彼はすべきです：あなたが周りに持っている嫌いなプロジェクトをチェックし、彼にそのメンテナンスを割り当てます。

通常、これらは文書化が不十分なプロジェクトであり、修正が容易だったものを修正するために何が起こっているのかを理解しようとして何時間も無駄にしています。この種の経験が彼を最新にしたくなければ、正しい有用な文書は何もありません。

私の過去のプロジェクトの1つでは、多数のコメント（アルゴリズム、結果、またはいくつかの基本的なJavaDoc）が欠落していたため、私は彼に130の問題を作成することにしました。3週間後、彼は280件の問題を抱えていたため、コメントを書くことにしました。

コメントには1つの目的があり、1つの目的のみがあります。

なぜこのコードはこれを行うのですか？

コメントで理由が説明されていない場合は、削除する必要があります。コードを乱雑にする役に立たないコメントは役に立たないほど少なく、積極的に有害です。

私は自分のコメントをIDEで最も明白なものにする習慣があります。緑の背景に白のテキストで強調表示されます。本当にあなたの注意を引きます。

これは、コードが何をしているのかを説明し、コメントがそれをしている理由を説明しているためです。これを十分に強調することはできません。

コメントの良い例：

/* Must instantiate clsUser before trying to encrypt a password because the code to 
   encrypt passwords only uses strong encryption if that module is loaded. */

悪い例：

/* instantiate clsUser */

コードの「セクション」としてコメントを使用している場合：マンモスメソッドを小さくて便利な名前付き関数に分割し、コメントを削除します。

次の行で何をしているのかを言っている場合：コードを自明にし、コメントを削除します。

コメントを警告メッセージとして使用している場合：理由を必ず言ってください。

ここで答えを補足するために、「正しく実行したい場合は、自分で行う必要があります」を追加できます。

私は「最高のコードコメンター」になることを意味するのではなく、この他の開発者に何をしてほしいかを示すロールモデルになることを意味します。彼らは示すことは話すよりも効果的だと言います。質の高いコメントのメリットを実証できる場合、またはこの他の開発者を（メンターが望む範囲で）メンターすることさえできれば、コードコメントの採用に成功する可能性があります。

同様に、家には私がやる気のない家事がいくつかあります。しかし、それらの同じ雑用は偶然私の妻の「ペットピーブ」雑用である... 彼女が幸せになるために行われなければならない雑用。同じ状況がその逆にも当てはまります。この他の開発者はあなたとは異なる優先順位を持ち、すべてに同意するわけではないことを受け入れる必要があると思います。私の妻と私が見つけた解決策は、それらの「ペットピーブ」家事のために、私たちは自分でやらなければならないということです。

シンプル：従業員がコメントをしない場合はshift+alt+j、コードの入力と同時に各メソッドで自動コメントを押すように指示します。これらの問題を回避するためにコードを修正してください。