コードでコメントを付けることを嫌うチームメンバーにどのように対処できますか？
私のチームメンバーの1人は、彼のコードでコメントを書くことを常に避けています。
彼のコードは自己文書化されておらず、他のプログラマーは彼のコードを理解するのに苦労しています。
私は何度か彼に彼のコードにコメントするように頼みましたが、彼は言い訳をするか、後でそれをするだろうと主張します。彼の懸念は、コメントを追加すると時間がかかりすぎてプロジェクトが遅れるということです。
彼に自分のコードを適切に文書化するよう説得するために、彼にどんな議論を提示できますか？
そのメモで、コードのコメントに焦点を合わせるのは間違っていますか、これは対処すべきより大きな問題を示していますか？
コメントだけではコードが改善されるわけではなく、「より多くのコメント」を要求するだけで/* increment i by 1 */スタイルのコメント。
だから自問してくださいなぜあなたはそれらのコメントが欲しいです。 「ベストプラクティス」は、理由を理解しない限り、議論の対象にはなりません。
現在、コメントを使用する最も印象的な理由は、コードが理解しやすくなるためです。コメントがないことに不満を言うとき、彼らは無知なオウムであるか、使用しているコードを理解するのに苦労しています。
コメントの欠落について文句を言わないでください：判読不可能なコードについて文句を言います。 さらに良いことに、文句を言わないで、コードについて質問し続けるだけです。わからないことがあれば、それを書いた人に聞いてください。とにかくそうするべきです。判読不能なコードでは、さらに質問するだけです。そして、後でコードの一部に戻ってきて、それが何をしているかを正しく覚えているかどうかわからない場合は、同じ質問を繰り返してください。
コメントで修正でき、同僚の頭脳が機能している場合、いつか愚かな質問をするよりもコードにコメントする方がはるかに簡単であることがわかるでしょう。そして、質問が思いつかない場合は、おそらくそのコードは完全に読み取り可能であり、誤りがあるのはあなたです-結局のところ、すべてのコードにコメントが必要なわけではありません。
人々のスキルの最前線で、絶対に侮辱したり非難したりするような音は避けてください。質問は真面目で正直にしてください。
自己文書化コードや役立つコメントを書くのに苦労した多くの開発者に会いました。これらの種類の人々は、それを正しく行うための十分な自己規律または経験を欠いていることがよくあります。
機能しないのは、「コメントを追加するように指示する」ことです。これは彼らの自己規律も経験も増加させません。私見機能する可能性のある唯一のことは、頻繁なコードレビューとリファクタリングセッションを行うことです。開発者がタスクを完了したら、理解できないコード部分を説明できるようにします。すぐにコードをリファクタリングまたは文書化して、6か月後に両者が理解できるようにします。
これを数か月間、少なくとも週に2回行います。運が良ければ、他の開発者がこれらのセッションを通じて学習し、レビューの頻度を減らすことができます。
誰もまだコードレビューについて言及していないことに驚いています。コードレビューをしてください！彼が質の悪いチェックインをしているとき、単に「コメントを追加」と言ってはいけません。常に質問し、彼に彼のコードが何をするのか、そしてその理由を教えてもらいます。メモする。次に、コードレビューの最後に、メモのコピーを渡して、質問をかなり明確にするように伝えます。コメントを増やすか、コードをリファクタリングして品質を向上させる（できれば後者が望ましい）
これは、チームワーカーが生成するコードによって異なります。ボブおじさんから Clean Code の本を読んだ場合、彼は実際にコードにコメントをしないを追加することを好むことがわかります。コード自体が読みやすいようであれば、コメントはほとんど必要ありません。
そうでない場合、または交渉できないポリシーのためにコメントが必要な場合、主な質問は、彼を望んでいるのはあなただけかどうかです/コメントを書くか、それがチーム全体であるか、チーム/プロジェクトリーダーであるか。それがあなただけの場合は、他の同僚に相談して、それがそれほど大したことではない理由を見つける必要があります。
プロジェクトリーダーにコメントがない場合は、completenessの一部としてコメントを要求することもできます。つまり、送信されたコードにコメントがない場合、作業はまだ完了していません。現在の作業が終了し、そのためにコメントが必要になるまで、彼は他の作業を続けることはできません。ただし、この種の強制は恐ろしいコメントをもたらす可能性が最も高いことに注意してください（コードコメントの繰り返しの負荷が予想される）。
私の控えめな意見の中で実行可能な唯一の方法は、あなたや他の皆がコメントから得る実際の利益について議論することです。もし彼/それが単なる議論でそれを理解しないなら、常に困難な方法もあります。彼らに新しいコードを書かせる代わりに、彼らに既存のコードで彼らを働かせます。可能であれば、2つの異なる作業領域を見つける必要があります。1つは適切な有用なコメントがあり、もう1つはコメントが不足しています。自分の作業に関して、他の誰かの読み取り不能でコメント化されていないコードを読み取る必要があることは、目を見張るものです。
私たちは皆、一度はそこに行ったことがあり、ずさんな作業をしたソースの元の作者に腹を立てていました。私たち一人一人も同様に著者であるということを理解するのは、読みやすさを気にする必要があることを理解させる追加の反省です。したがって、この反省を促進するために、後で結果を同僚と話し合うことを忘れないでください。
指示に従えない従業員がいる場合は、その従業員を叱責し、それが彼のキャリアの向上に役立たないことを明確にしてください。コーディングスタイルの一貫性はチームにとって非常に重要です。他の全員がコメントを書いていて、これがそうではない場合、コーディングスタイルが損なわれます。
とはいえ、おそらく彼を助けることができます。私の経験では、誰かがそのコメントに抗議するとき時間がかかりすぎるなどの心理的な障壁があります…
- 彼は自分のコード/デザインの選択について自覚しており、それらを散文でレイアウトしたくありません。 （コードレビューは、誰かを安心させるだけでなく、誰かの自信を高めるのにも役立ちます。）
- 彼は非常に直線的に働いており、あまり先を考えていません。別の方法で意図を構成するために、彼が作業メモリから書き込もうとしている即時コードをアンロードしなければならないため、コメントは苦痛です。 （これが真実である場合、コメントは彼のコード品質にとって非常に重要になります。）
- 歴史的に人々は彼のコメントを理解していません。
プログラマにとって、コメントはテストのようなものであることを認識することが重要です。コメントはjustではなく、将来の使用のために–プログラマ自身のためのものです。彼らは彼に彼のアプローチについて異なる考えを強いる。
これは、CI、テスト、またはコードレビューに代わるものではありません。これは、コーディング自体の多くの重要な部分の1つにすぎません。
コードレビューソフトウェアを入手し、それを上手に使用してください。
私たちはキルンを使用しています。私たちはすべてのチェンジセットをレビューする必要があるというポリシーを持っています（ただし、開発者はタグおよび競合のないマージについて自分でレビューをレイズ/承認することができます（ほとんどの場合、rebaseifを使用します）。これにより、レビューなしでチェンジセットをすばやく見つけることができます）。
明確でないコードは、コードレビューが拒否される理由です。修正がコメントであるか、より明確なコードであるかは関係ありませんが、レビュー担当者はそれを理解できなければなりません。一部の開発者はコードの書き直しを好みますが、他の開発者（私も含む）は、コメントで意図を表現する方が簡単だと感じることがよくあります（コードはそれが何をするかを簡単に示すことができますが、何を示すのが難しいすべきか）。
コードの明確さについて疑問がある場合は、レビュー担当者が常に勝者となります。もちろん、彼らが書いたので、著者はそれを理解しています。他の人に明確にする必要があります。
Kilnのようなソフトウェアを使用することで、変更セットを見落とすことはありません。私の開発チームの誰もがこの方法でそれを好みます。コードレビューソフトウェアは、コードの品質とアプリケーションの品質の両方に大きな影響を与えました:-)
開発者が最初にソフトウェアを導入するときに拒否されたレビューで防御的になるのは簡単ですが、私の経験では、物事がこのように優れていることを認識して受け入れるのにそれほど長くはかかりません:-)
編集：また、注目に値する、私たちは開発者が口頭でまたはレビューのコメントで暗号コードを説明しないようにします。不明な点がある場合は、コード内（コメント内、またはリファクタリング内）で説明するのが最適です。次に、同じレビューに新しい変更セットを追加します。
興味深いことに、自然言語に適用されるreadabilityは、読みの速さと理解力によって測定されます。確かに単純なルールを採用できると思います特定のコードコメントでこのプロパティが改善されない場合は、回避できます。
なぜコメントなのか？
コードコメントは埋め込みドキュメントの形式ですが、ハイエンドプログラミング言語には、言語自体の要素を使用して（意味のあるコードの）過剰に「ドキュメント化された」プログラミングを回避する方法がいくつかあります。また、コードをプログラミングテキストブックのリストに変換することもお勧めできません。個々のステートメントは文字通りほぼトートロジーで説明されています（すでに提供されている回答の「/ * increment i by 1 * /」の例に注意してください）。言語に不慣れなプログラマーだけに。
それにもかかわらず、それは本当に「すべての悪の源」である「文書化されていない」（しかし無意味な）コードにコメントしようとする意図です。 「完全に文書化されていない」コードの存在自体は悪いシグナルです-それは構造化されていない混乱か、神秘的な失われた目的の奇抜なハックのどちらかです。明らかに、そのようなコードの価値は少なくとも疑わしいものです。残念ながら、常に例があります。実際にコメントを（視覚的にグループ化された）フォーマットされたコード行のセクションに導入する方が、新しいサブルーチンにラップするよりも（「愚かな一貫性」に注意してください） 。
コードの可読性！=コードコメント
読みやすいコードは、コメントによる注釈を必要としません。コードの特定の場所ごとに、この特定のコードが達成するはずのタスクのコンテキストが常にあります。目的が欠けていたり、コードが不思議なことをしたりする場合=絶対に避けてください。奇妙なハックによるコードの作成を許可しないでください。これは、バグのあるテクノロジーと、時間や興味の欠如を組み合わせて基盤を理解した直接的な結果です。プロジェクトで神秘的なコードを避けてください！
一方、Readable program = code + documentationには、コメントの正当なセクションを複数含めることができます。 「APIへのコメント」ドキュメントの生成を容易にするため。
コードスタイルの標準に従う
おかしなことに、問題はコードにコメントを付ける理由ではなく、チームワークについてです-高度に同期されたスタイルでコードを生成する方法（他の誰もが読み取り/理解できる）。あなたの会社ではコードスタイルの標準に従っていますか？その主な目的は、リファクタリングを必要とし、「個人的」かつ「主観的」にあいまいすぎるコードの記述を避けることです。したがって、コードスタイルを使用する必要があると考えると、それを適切に実装するための真剣なツールが存在します。まず、人々の教育から始まり、コードの品質管理（多数のリントなど）と（改訂）まで自動化されます。制御統合）コードレビューシステム。
コードを読みやすくするエバンジェリストになる
コードが書き込まれるよりも頻繁に読み取られることに同意する場合。アイデアの明確な表現と思考が明らかに重要である場合、コミュニケーションにどの言語が使用されているかに関係なく（数学、機械コード、または古い英語）。あなたの使命が代替的思考の鈍く醜い方法を根絶することである場合（申し訳ありません） 、最後の1つは別の「マニフェスト」からのものです。.質問し、ディスカッションを開始し、コードクリーニングに関する考えさせられる本を広め始めます（おそらくBeckのデザインパターンに似ているだけでなく、すでに述べたように RC Martin ）プログラミングのあいまいさを解決します。重要なアイデアの箇条書きの一節に続きます（読みやすさに関するO'Reillyの本から引用）
- コードのすべての行に適用されるヒントを使用して、命名、コメント、および書式設定を簡素化します
- プログラムのループ、ロジック、変数を調整して、複雑さと混乱を減らします
- コードのブロックを再編成して一度に1つのタスクを実行するなど、機能レベルでの攻撃の問題
- 徹底的かつ簡潔で、読みやすい効果的なテストコードを作成する
「コメント」を省いても、まだたくさん残っています（おそらく、コメントを必要としないコードの記述は、すばらしい演習の1つです）。意味的に意味のある識別子に名前を付けることから始めるのがよいでしょう。次に、論理的に接続された操作を関数とクラスにグループ化して、コードを構造化します。等々。より優れたプログラマーはより優れたライターです（もちろん、他の技術的スキルが与えられていると想定しています）。
コードのコメントに焦点を合わせるのは間違っていますか、これは対処すべきより大きな問題を示しているのですか？
幾分。優れたコードにはコメントは必要ありません。しかし、あなたが言ったように、彼のコードは自己文書化されていません。だから私はコメントに焦点を当てません。開発者のスキルと職人技の向上に焦点を当てる必要があります。
それを行うにはどうすればよいですか？レビュー/リファクタリングセッションに関するDoc Brownの提案は良い考えです。私はペアプログラミングがさらに効果的だと思いますが、実装するのもかなり難しいかもしれません。
まず第一に、私はあなたがコメントについてのあなたのアプローチに再び取り組むことを提案するでしょう。
それらがAPIレベルのドキュメントコメント（後で公開）である場合、この開発者は単に仕事をしていません。ただし、他のすべてのコメントについては注意してください。
私がそれらに遭遇するほとんどの場合、コメントは悪です。理由をよく理解するには、 "クリーンコード" by Robert Martin のコードコメントの章を読むことをお勧めします。
コメントはいくつかの点でコードを傷つけます：
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）コメントはコードを散らかり、非常にまれに値を追加しません。
私の解決策：コメントを追加する代わりに、コメントをすべて削除してみてください！
コメントに関する極端な意見をしばしば考慮すると、私は検討するのをためらいます。
あなたが（判読不能な）コードを書くつもりならそれを適切に文書化すべきだと私が提示できるいくつかの議論は何ですか？
保守可能で読み取り可能なコードの記述方法を理解するには、時間、練習、経験が必要です。経験の浅いプログラマー（そして悲しいことに経験豊富なプログラマーの多く）は、しばしばIkea効果（ [〜＃〜] pdf [〜＃〜] ）に悩まされています。それは、彼らがそれを構築し、それに非常に精通しているためであり、彼らはコードが素晴らしいだけでなく、読みやすいと確信しています。
その人が優れたプログラマーであるならば、どんな文書も必要とされても、ほとんどありません。しかし、ほとんどのプログラマーは素晴らしくなく、彼らのコードの多くは「可読性」部門で苦しむでしょう。平凡な、または開発中のプログラマーに「コードを説明する」ように依頼することは、より批判的な目でコードを表示するように強制するのに役立ちます。
これは、コードを「文書化」することを意味しますか？必ずしも。例として、過去にこの問題を抱えた同様のプログラマーがいました。私は彼に文書化を強いた。残念ながら、彼のドキュメントは彼のコードと同じくらい判読できず、何も追加していませんでした。振り返ってみると、コードレビューの方が役立つでしょう。
あなた（またはデリゲート）は、このプログラマーと一緒に座って、彼の古いコードのいくつかをプルアップする必要があります。彼がそれに取り組んでいるだけで彼が知っている新しいものではありません。最小限の操作でコードを説明するように依頼する必要があります。これは、彼が自分のコードを書いて説明する別の「文書化」セッションにすることもできます。その後、彼はより良いアプローチに関するフィードバックを得る必要があります。
余談ですが、コードの「読みやすさ」がいかに優れているかに関係なく、ドキュメントが必要になる場合があります。 APIにはドキュメントが必要です。非常に技術的で複雑な操作には、プログラマーが関係するプロセスを理解するのに役立つドキュメントが必要です（多くの場合、プログラマーの知識の領域外）。複雑な正規表現のようなものは、照合対象を実際にドキュメント化する必要があります。
これは主にtdammers回答の拡張ですが、コードレビューを定期的に実行します。
彼（および他の開発者）が座ってコードを確認し、多かれ少なかれ上司や同僚の前で防御することで、誰もがより優れたプログラマーになり、比較的短期間で真の価値が追加されます。短期的には、問題の開発者に、レビューの時点で自分のコードに適切にコメントする言い訳はありません。
編集：なぜ誰かが私の提案を反対票を投じるのかわかりません-おそらく私はコードレビューの利点が常識になると当然と思っていました...実践のコミュニティ分析についてはこのスレッドを参照してください：
チームメンバーが別のチームメンバーのコードを（何らかの理由で）理解できない場合。次に、そのチームメンバーは、元のコードを書いた人（正気なリビジョン管理システム）を見つけることができ、コードの作成者に直接説明するよう依頼することをお勧めします（例：自分の机に向かい、座って話し合います）。
この場合、コメントが不足していることが問題である場合、コードに適切にコメントしていない人は、自分のしたことを説明するために多くの時間を費やします。そして、もし彼らが賢いなら、それらすべての説明に時間を費やすことを避けるためにコメントを追加し始めるでしょう。
チームメンバーにお互いに説明を求めるように促すことは、他の理由でも価値があることに注意してください。たとえば、チームメンバーは経験が浅く、経験豊富なチームメンバーから物事を学ぶことができます。
ほとんどの場合、チームメンバーが互いに説明を求め合うように促すことで、自己バランスシステムを作成します。異なるチームメンバーが互いに「自動調整」します。
コードレビューの回答が大好きですが、おそらく私のプロセスも少し役立つでしょう。
コメントは大好きですが、最初のパスでコメントをコードに追加することはほとんどありません。多分それは私のスタイルかもしれませんが、開発中に同じコードのセクションを3〜5回ヒットします（リファクタリング、テストの作成など）。
少し混乱したり、コードのセクションについて誰かが質問したりするたびに、意味のあるように修正しようとします。
これは、コメントを追加するだけで簡単になり、混乱する一連の操作を独自の関数に削除したり、新しいオブジェクトを抽出するような大きなリファクタリングをトリガーしたりできます。
グループの全員がコードを他人に読めるように「所有する」ことをお勧めします。つまり、誰かがあなたのコードについて質問するたびに、変更を行うことを約束します。すぐに変更する人！
これを「チーム契約」の一部として真剣に検討することを検討してください（契約がない場合は、契約を作成してください）。つまり、誰もがそれに同意し、壁のどこかに設置して、 t同意したことについての質問。
多くのプロジェクトには、コードドキュメントが必要です。インターフェイスドキュメント、設計ドキュメントなどです。
一部のプロジェクトでは、このようなドキュメントをコードコメントに入れ、Doxygen、Sphinx、Javadocなどのツールで抽出して、コードとドキュメントの一貫性を保つ必要があります。
このようにして、開発者はコードで有用なコメントを書く必要があり、この義務はプロジェクト計画に統合されます。
適切なコーディング標準に従っている場合、必要なコメントの数は最小限になります。命名規則は重要です。メソッド名と変数名は、それらの役割を説明する必要があります。
私のTLは、コメントを減らすことを勧めています。彼は私のコードが理解可能で自己説明的であることを望んでいます。簡単な例：検索パターンに使用される文字列型の変数名
var str1:String="" //not uderstandable
var strSearchPattern:String="" //uderstandable
ほとんどの回答とコメントのヒントを述べるつもりです。おそらく、認識されたソリューションをプッシュするのではなく、ここで実際の問題を理解する必要があります。
あなたは彼のコードにコメントを見る意欲があります。 なぜ？あなたは理由を述べました。 なぜその理由はあなたにとってとても重要ですか？彼は代わりに何か他のことをすることに意欲的です。 なぜ？彼は理由を与えるでしょう。 なぜその理由は彼にとって非常に重要ですか？競合が実際に発生するレベルに到達するまでこれを繰り返し、両方で対処できる解決策を見つけてください。コメントとはほとんど関係がないと思います。
たぶん、この人は、優れたコーディング規律を認められる必要があり、なぜ彼が書いたコードを他の人が理解できることが重要なのか。
私はキャリアの中で本当にひどいコードベースに取り組んできました。コードがうまく整理されておらず、変数名が非常に貧弱で、コメントが非常に悪いか存在しないため、コードベースが私の生産性を損ないました。理解できないコードベースを修正または改善するために作業することはできません。また、初心者が理解できない方法でコードが記述されている場合、実際に作業するよりも理解するために多くの時間を費やすことになります。
厳しい経験に勝る教師はありません！
すべてのコードベースには、恐ろしいビットが潜んでいます。システムの一部は、何かを壊すのを恐れているので誰も触りたくないでしょう。それらのコードの。そのコードがコメント化されておらず、自己文書化されていない場合、問題はさらに悪化します。
そのようなコードベースのビットを見つけて、面倒なコーダーにそれを任せることをお勧めします。彼にそれの所有権を与え、それを彼の責任とし、十分に文書化されていないか、短期間で理解することが不可能なために維持できないコードに取り組むことの本当の痛みを彼に学ばせます。数か月の作業を経て、きっと彼は動き出すだろう。