他の人に自分のコードにコメントするよう説得するための良い議論は何ですか?
多くのプログラマーが、自分自身や他の人のためにドキュメントを残すよりも、コメントなしでコードを書くことの認識速度を好むことに気付きました。私が彼らを説得しようとすると、「メソッド/クラス名はそれが何をするかを示すべきだ」などの生半可なことを聞くようになります。
コメントに反対の場合は、コメントを残してください。これは、他の方法ではなく、コードにコメントするよう人々を説得しようとする人々のためのリソースであるべきです. :-)
その他の関連する質問は次のとおりです: Commenting code , Do you comment your codeおよびHow would you like your comments .
「何」ではなく、「なぜ」のみコメントしてください。これまでのところ、クラス、メソッド、または変数名から、それが何をし、何に使用されるかが明確になるはずです。コメントする代わりに、そうでないところをリファクタリングします。
このアプローチを取ると、コメントが得られ、有益なコメントが得られます。プログラマーは、自分が何かをしている理由を説明するのが好きです。
6 か月前の独自のコードを表示します。彼らが 2 ～ 4 分以内にそれが何をするかを正確に理解して概説できない場合、あなたの主張はおそらく成されています。
私の意見：
私はしません。メソッド/クラス名は、それが何をするかを示す必要があります。そうでない場合は、メソッドまたはクラスがやりすぎているか、名前が不適切です。
私は、何ではなく、なぜコメントするのが好きです。コードがあるアプローチを別のアプローチよりも優先して使用している理由が明確でない場合は、コメントしてください。コンパイラのバグを回避するために未使用のハック変数を追加する必要があった場合は、その理由をコメントしてください。しかし、"//Connect to database" のようなコメントは、悪いコードまたは悪いポリシーの兆候です。ConnectToDatabase() という名前のメソッドの方がはるかに優れています。そして、「//Determine DB server IP」が含まれている場合、おそらく「DetermineDbServerIPAddress()」という名前のメソッドに引き出されるべきです。
設計は文書化できますが、コメントは一般に、そのレベルの文書化には適していません。設計に関する知識と、その理由に関するいくつかのコメントがあれば、何をどのように行うかは明らかです。そうでない場合は、コードにコメントするよう説得するのではなく、コードを改善してもらいます。
おそらくそれは、経験から学ばなければならないことです。具体的には、6 か月後に自分のコードに戻って、それを書いたときに何を考えていたのか (または何を考えていたのか) を理解しようとする経験です。確かに、コメントはそれほど悪い考えではないと私は確信しました。
リファクタリングするために、いくつかの（〜500行、最小）コメントなしの恐ろしいスパゲッティコードを提供してください。変数に論理的な名前が付けられていないことを確認してください。空白はオプションです。
そして、彼らがそれをどのように気に入っているか見てください！
厳しすぎるが、一度に 2 点を獲得する。
このコードは彼らに由来するものであってはならないことを強調しておきます。コメントは、数か月先の自分のコードを理解するのに非常に役立ちますが、他の人のコードの複雑な部分を理解するためにも、ほぼ不可欠です。彼らは、他の誰かが自分のしていることを理解する必要があるかもしれないことを理解する必要があります.
最後の編集: コメントの質も非常に重要です。一部の開発者は、コードとコメントの比率がほぼ 2:1 ですが、それでは良いコメントにはなりません。コード内のコメントは驚くほど少なくても、意味のあるものにすることができます。
コードを読んでも、コードが何をするべきかではなく、何をするかしか分からないことを彼らに思い出させてください。
あなたまたは他の開発者がまだCodeComplete（またはCode Complete 2）を読んでいない場合は、実行を停止して読んでください。
際立っていることの1つは、「関数は1つのことだけを実行し、それをうまく実行する必要がある」ということです。そのような関数が1つのことから名付けられたとき、それはうまくいきます。コメントのためにさらに何が必要ですか？
コメントには、説明するはずのコードと同期しなくなる傾向があります。結果は、そもそも元のコメントがない場合よりも悪くなる可能性があります。それだけでなく、開発者はコメントが古くなり、信頼できないことを知っています。したがって、彼らはコードを読み、とにかく実際に何をしているのかを自分で識別します！これは、そもそもそこにコメントを置くという点を無効にします。
関数名についても同じことが言えますが、元々は名前が付けられていた可能性がありますが、名前に含まれていない新しい操作が時間の経過とともに追加されています。
すべてのコメントは、開発者が画面全体でより多くを見ることができるように、より近くに配置することを好むコード行を分離しているようです。私は、理解しなければならないコメントがたくさんあるコードに対する自分自身の反応を知っています。コメントをすべて削除します。これで、コードが何であるかを確認できます。
一日の終わりに、物事を正しくするために時間を費やす場合は、コメントを書くだけでなく、コードを合理的に自己記述できるようにコードをリファクタリングする方がはるかに効果的です。このような演習は、コードの一般的なチャンクを特定するなど、他の方法で成果を上げます。
また、多くの優れた開発者は、すべての仮定とあいまいさを備えたはるかに精度の低い人間の言語よりも、鮮明でクリーンなC＃、Javaを作成することを好むことも覚えておく価値があります。常識のあるほとんどの人は、どれだけの詳細が十分な詳細であるかを知っていますが、優れた開発者は「ほとんどの人」ではありません。そのため、次のようなコメントが表示されます\\adds a to b and store it in c（極端すぎますが、要点はわかります）。
彼らが嫌いなことをするように頼むことは、率直に言ってあまり得意ではありません（あなたがそれが正しいことだと確信しているとしても）、単にすでに負けた戦いです。
私たちの戦略は、体系的なコードレビューを行い、適切に文書化されていないコードを拒否することです（コメント、適切な関数の命名と編成などを通じて）。レビュー担当者に明確でない場合は、作業台に戻ります。
「昨日、あなたのコードの一部を読まなければなりませんでした。理解できましたが、目的をどのように達成したかを説明する適切に選択された 5 行以下のコメントがあれば、約 1 回で読むことができたでしょう」と言うでしょう。 -10 分の 1 の時間で、代わりに問題を理解することを心配することができた.読みやすいドキュメントとコード アンサンブルがあれば、開発者としての価値は低くなります。」
私はずっと前にこれを掘り下げていました。あなたが何かを書いて、合理的な能力を持つ誰かがそれを理解できない場合、それはあなたのせいであり、彼または彼女のせいではありません. これは自然言語での記述にも当てはまり、プログラミング言語での記述にも当てはまります。
私はあなたに皮肉を言っているわけではありませんが、質問を次のように言い換える必要があります。他の開発者にチームとして働くように説得するにはどうすればよいですか?
真剣に、あなたが自分の心を読むことができると思っている人もいます。
あなたがアジャイル チームの一員である場合、コードは集合的に所有されているため、コードがコメントされていない、ぎこちない、または読みにくい場合は、先に進んで変更 (リファクタリング) して、理解できるようにします。人々が不平を言う場合は、その理由を率直に伝えてください。あなたが理解できないと思ったこと、そして誰もコードを所有していないこと。
コメントについても同様の議論がありました。これは、コードにコメントするときに人々が従う規則に関するものです:あなたのコードにコメントすることについてのあなたの「厳しい規則」は何ですか? . 一部の回答には、コードにコメントを付けたいという非常に正当な理由もあります。
人を説得する最善の方法は、自分でそれを実現させることです。よくコメントされたコードをデバッグするようにします。それは彼らに良いコメントがどのように見えるかを示します - コメントは本当に関連する情報を伝えない限り役に立ちません (コードは「何を」記述しているので、それは通常「理由」です)。彼らはそれがいかに簡単であるかに気付くでしょう。次に、古いコードの一部に戻してもらいます。彼らはそれがどれほど難しいかに気付くでしょう。何をしてはいけないかだけでなく、何をすべきかを示しました (これはより重要です)。もう何もする必要はありません。さらに、口頭で説得する必要はありません。彼らは、独自の方法でコードにコメントする必要性を理解する必要があります。これはもちろん、コメントする必要があるコードが自明ではないことを前提としています。
コメントを求めるあなたの欲求に知恵を示してください。
少ないほうがいいですね。
量よりも質を重視します。
私のチームでは、特定の API のすべてにコメントするよう求められていました。一部の開発者は、メソッド名とシグネチャを見てコメントを自動的に生成するツールを使い始めました。
例えば：
/// <summary>
/// Gets the Person.
/// </summary>
/// <returns>
/// A Person
/// </returns>
public Person GetPerson()
{
}
画面領域のより大きな浪費を考えられますか? 新しい情報を提供しないコメントを読むことよりも、脳サイクルの浪費が大きいと思いますか?
メソッドの署名から明らかな場合は、それを言わないでください。私が数秒でそれを理解できるなら、それをコメントに入れないでください. 他の人が言ったように、何をしたかではなく、なぜそのようにしたのかを教えてください。何をするのかが明確になるようにコードを書いてください。
あなたが持っている力に依存します...
非常に効果的な方法は、ピアベースのコードレビューの固定部分（コメントのポイント）にすることであることがわかりました。コードがひどくコメントされているというコメントがあった場合、私は開発者に満足のいくようにコメントさせます。つまり、基本的には、コードを印刷して読んで理解できるように、十分な量のコードを記述しなければなりませんでした。そして、私もそうします。
驚くべきことに、これはディケンジアンに聞こえますが、開発者に人気がありました。2つのことが起こりました。まず、人々は自分のコードにコメントし始めました。第二に、ひどくコメントされたコードは、開発者が自分たちが書いたものを完全に理解していないことの兆候になりました（そうでなければ彼らはそれを説明していたでしょう）。
唯一の本当の欠点は、バグ修正などのためにコードが改訂されたときにコメントを維持しなければならなかったことです。これは実際の開発ショップで実施することはほとんど不可能でしたが、十分なグッドプラクティスが定着すると、自然に起こりました。 。
ところで、私はドクトエフスキーの小説よりもコード自体のコメントをドキュメント文字列として好む。前者は、後続のプログラマーにとって有用な支援です。後者は、ドキュメントを埋め尽くし、すべての人を誤解させる、古くなったテキストの長い部分にすぎません。
コメントは徹底的で、意図のレベルで（なぜそうしないのか）書かれ、まれである必要があります。
コードを書くとき、当然のことながら、私はかなり重くコメントする傾向があります。次に、コードの理解度を低下させることなく、戻ってできるだけ多くのコメントを削除しようとします。> 80％の場合、これは適切な名前のメソッドを抽出するのと同じくらい簡単です。これにより、通常、コード自体の情報を複製するだけのコメントが生成されます。それを超えて、コメントを「必要とする」コードのセクションがある場合、私はそれを単純化するか、より明確にする方法を探します。
コードは自己文書化する必要があり、適切な手法を使用すれば、95％の道のりを非常に簡単に得ることができます。チェックインするコードにコメントが残っている場合は、通常、失敗と見なします。
例によってリードします。開発者は、The Right Thing を見るとすぐに動揺してしまうため、実際に実践されている堅実なプラクティスを見ると、同じことをするようになるかもしれません。さらに、コードの保守性とコメントに対応するコード メトリクスを採用するようグループに勧めることもできます。たとえば、コード分析は、要約ドキュメントのないメソッドに対してバグを生成します。
私の現在の職場での現在のコーディング標準は、すべての関数にコメントすることです。このような空欄のルールは有害であり、決して実施すべきではありません。コメントを追加すると可読性が失われる状況があります (いくつかはよくあることです)。
class User {
getUserName() { /* code here */ }
}
上記のコードに関数ヘッダーを追加するポイントは何ですか? besdies が「ユーザー名を取得する」と他に何を言うつもりですか。すべてのコードにコメントを付ける必要はありません。私の経験則は次のとおりです。関数のシグネチャが追加しない有用な情報を追加しない場合は、コメントをスキップしてください。
なじみのない API を使用してもらいますが、API ドキュメントにアクセスできないように、インターネットに接続されていないマシンでプログラミングを行います (最近見つけた場合)。これは、他の開発者が非ドキュメンターのコードを使用しようとしている場合に、実際に強制していることです!
ここでも、2 つの異なるコメントを区別する必要があります。
API コメント(javadoc または他の同様の種類のドキュメント):制限シナリオ (null オブジェクトや空の文字列などの境界条件など) で独自のコードを使用するように依頼し、実際に何を覚えているかを確認できます。それらの場合の独自の機能
（そのため、limit-value を含む完全な javadocが必要です）
内部コメント(ソース コード内): コード化した関数について説明するよう依頼することができます。循環的複雑度レベルが非常に高い関数を選択するだけで、さまざまなコード ワークフローと決定分岐のすべてに苦労している様子を見ることができます ;)
私は1つの微妙なテクニックを使用します：
プロジェクト内の警告のレベルをエラーとして報告するように設定しました。また、継続的インテグレーションサーバーは、各チェックイン時にXMLドキュメントとともにソリューション全体を構築しています。
開発者がコメントを書かないと、ビルドは失敗します！そしてその後、コメントを書かなければならないので、しばらくすると慣れてきました。
プレッシャーの面では攻撃的ではありませんが、彼らの行動を正す良い方法のように思います。
開発者がコードレビューに参加する必要があり、優れたコメントにさらされている場合は、手がかりを得ることができるはずです。実践が有用であると思わない場合は、査読者からフィードバックを得る必要があります。
それが失敗すると（あなたがスーパーバイザー/マネージャーであると仮定して）、それは彼らの業績評価の一部になります。測定できれば、それに基づいて評価することができます。
パッシブアグレッシブな開発者は最後のすべてのステートメントをそれほど微妙ではないFUとして文書化するため、スコアを付けるのはレビュー済みのコメントであることを確認してください。
私はHeadrick'sRuleと呼ばれるものを固く信じるようになりました。これは、誰かに何かをやる気にさせる良い方法は、やらないように苦痛を与えることだと気付いた同僚にちなんで名付けられました。
あなたの場合、コメントを付けていない開発者に、おそらく「プロジェクトのスリップを避けるために」昼食時に、おそらく「遅い」聴衆にコードを説明するために1〜2時間費やすように依頼することは大いに役立ちます。賢い人は-頑固な人でさえ-速く学びます！
私の意見では (ここでは .Net プログラミングについて話しているのですが)、コメントを付ける必要がある場合は、コードを読みやすくすることに失敗しています。答えは通常、リファクタリングです。
ただし、コメントを付ける必要がある場合は、コードの機能を説明するコメントではなく、常に「理由」タイプのコメントにする必要があります。
まあ、「あなたが自分のコードにコメントしなければ、自分のコードにコメントしてくれる誰かを見つけます」というアプローチは常にあります。
もっと穏やかに、彼らがやっていることを文書化してコメントしないと、チームをひどく失望させていることを彼らに伝えてください. 完全な一匹狼でない限り、コードは個人のものではありません。会社であろうとコミュニティであろうと、それはチーム、グループに属しています。
「コードを書く」＝「コマンド列を特殊言語で書く」＋「コメントを書く」
コードを書いているときにコードにコメントすることは自明です！すでに 3 ～ 4 か月前のコードにコメントしたことがありますか? （もちろん、あなたは持っています、そしてそれは楽しいこと以外のすべてでした！）
プロジェクトがすでに十分に文書化されている場合、新しいコードを追加するプログラマーは、同様の方法でコメントを書きたくなるかもしれません。
@James Curran私は100％同意します！私はあなたのコードを読んで、あなたがコンパイラーに何をするように指示したかを理解することができます。しかし、それはコンパイラにそれをさせることがあなたの意図だったという意味ではありません。私は、コードを書くたびに、私がやろうとしていたことを正確に実行すると信じるほど傲慢なプログラマーではないことを知っています. さらに、コードを書いた後、そのコードが何を意図しているかを説明しようとすることで、コード内のばかげた論理エラーを見つけるのに役立つことがよくあります。
クラスごとに 1 つか 2 つの文を書くのに 1 分もかからず、メソッドごとに 1 つの文を書くのに 30 分もかからないことを指摘するのも 1 つの考えです。
Javadoc コメントを使用して関数とインターフェイスを文書化し、Doxygen を介してコードを実行して、コードの見栄えの良い HTML ドキュメントを生成するように伝えます。涼しさの要因は、時には良い動機になることがあります.
私は10年間の開発で、コードについて何か役立つことを実際に教えてくれるコメントを見たことがありません。コメントは通常、古くなっているか、明白な状態です。あなたがそれらを書くとすぐに、それは維持するもう一つのことです。コメントするのに合理的なのは、正規表現またはおそらくアセンブラーコードだけだと思います。
コメントの可能性が必要な場合は、コメントしたいものを別のメソッドまたはクラスに引き出す必要があります。コードを文書化するもう1つの方法は、テストを作成することです。
実際にコーディングする前にメソッド/クラスが何をするかを書き留めておくことは、それを正しくするのに大いに役立ちます-そしてあなたはそれをコメントしました。
コードが意図を暗黙的に述べていることを確認する優れたエンジニアのみを採用してください（コメントなどを使用して）。仕事をしたい人は誰でもそれを正しくしなければならないでしょう。厳しいが、公平な、私見。
I am also in the camp of less comments the better, and in order for that to work it requires clear concise code that is to the point. So that is where i would start with them. Tell them they dont have to comment, as long as they write better, clearer, self commenting code.
絶対に必要な場合、コードが何をしているのかが明確でない場合にのみ、コメントを入れてください。
たとえば、12 行のコードの上にコメントがある場合は、メソッドに適切な名前を使用してメソッドにリファクタリングするか、メソッドの上にコメントを追加するだけです
また、良いコメントの重要性を開発者に示す最善の方法は、彼自身の過去のコードを見せることだと思います。
また、SandCastle のようなものの利点を示します。
「blabla コメントして、Why not the what blabla」
コードのコメントに関するすべての質問に対する簡単な答え...それに関する私の問題は、誰もが毎回同じことのように「なぜ」と「何」について話していることです。
明らかにそうではありません。何か新しいもの (API、フレームワーク、新しいプロジェクト、ツールなど) を発見すると、わからないことやその存在すら知らないことがたくさんあります。しかし、しばらくすると、多くのことがより意味のあるものになります。クラスの目的を理解するために、コード ジャングルに迷い込む必要はありません。
そもそも「なぜ」と「なに」は同じもので、このことは「？」に要約できます。時間をかけて学び、理解するうちに、「何」がますます把握しやすくなり、ついにはその存在を忘れてしまうほど明白になります。「何」が「より明確」になるにつれて、私の心は「なぜ」について自問するためのより多くのリソースを持ち、アーキテクチャ全体に対する私の理解はますます完全になります。
学習時間の最初にコードにコメントを入れた場合、「なぜ」にコメントしようとしても、経験豊富な人がすでに明白だと考えていることをコメントします（彼らはそれを「何」と呼び、コメントを言います無駄です）。学習曲線の大きな波が交差した後に書かれたコメントは、数が少なくなり、コメントされたものの非常に具体的な機能を説明します (このレベルの理解に達した人だけが理解できます)。
これについての最後のことは、コメントを読む時間を失ったことは一度もありません。また、コメントによって学習時間が短縮されることがよくあります。「コメントが多すぎる」コードを見たことがありません。私は（みんなと同じように）自分にとって役に立たないコメントをよく読んでいますが、「もっと役に立つことをするためにコメントを読むのにずっと時間を費やしていたら！」と思ったことは一度もありませんでした。最新のすべての IDE が大きなコメントを非表示にできる UI を提供しているという事実を考えると、役に立たないコメントを書くことがなぜ悪いと見なされるのか理解できません。
より主観的な観点から言えば、空の白い背景にインデントされたいくつかの単語よりも、コードのページにいくつかの役に立たない緑色の単語が表示される方が好きです。
私は、15 ページの長さの暗いメソッドに何もないよりも、コードの明らかな部分に役に立たないコメントを好む....
残念なことに、圧倒的多数のプログラマーが、不適切なドキュメントの反対側にたどり着くまで、自分のコードに適切にコメントすることはありません。明確なコメントのないアプリの維持に行き詰まるのは、まさにひどいことです。通常、その直後 (IME)、コード フロー内のコメント。
はい、これは私に起こりました。今、徹底的にコメントします。
ほとんど修辞的な質問です。本当に優れたコーダーは、実際には多くのコメントを必要としません。残念ながら、これらの貴重な数はほとんどありません。つまり、コメントなしではコードが読めないことを人々に伝えています。
プログラマーがきれいな仕事をするのに十分な時間をとることはめったにありません。私たちは常に何かを単体テストして、結果を吐き出し始めるかどうかを確かめるために大急ぎでやっているようです。したがって、私の最終的な答えは、平均的なプログラマーが質の高い時間を持つことができるような雰囲気の職場を見つけることです。私は、Google に 2 回申請して 2 回却下されました。
他のすべての回答が、プログラマーにコメントを書くように「説得する」ことについて話している理由がわかりません。動物や子供には正の強化を使用しますが、大人には論理を使用します。
コメントを書くたびにクッキーを渡してください。例えば、本当のクッキーや「素晴らしい人」などです。必要に応じて、コメントを書かないことには常に罰があります。もちろん、罰するのに上司である必要はありません。公の場での嘲笑、軽蔑、および一般的な排除は、十分に強力なテクニックです。
コメントはコードへの洞察を提供するためにうまく使用できますが、コメントを残すよりも、プログラマーに説明的なコードを書くように勧める方が価値があると私は主張します。明確な名前と署名を使用してより小さなメソッドを作成することは、最初から適切に作成できた可能性があるコードを説明する長いとりとめのないコメントよりも、最終的にはより効果的です。