コードにコメントするよう人々を説得する方法 [終了]

https://stackoverflow.com/questions/159597

03-07-2019
|

質問

他の人に自分のコードにコメントするよう説得するための良い議論は何でしょうか?

多くのプログラマは、自分自身や他の人のためにドキュメントを残すよりも、コメントなしでコードを書く体感速度を優先していることに気づきました。彼らを説得しようとすると、「メソッド/クラス名はそれが何をするのかを示すべきだ」などといった中途半端な話を聞くことになります。彼らの考えを変えるために何と言いますか？

コメントに抵抗がある場合は、コメントを残してください。これは、コードにコメントするよう人々を説得しようとする人々にとってのリソースであるべきであり、そうでない場合はそうではありません。:-)

その他の関連質問は次のとおりです。コードのコメント化, コードにコメントを付けますかそしてコメントはいかがですか.

解決

人を説得する最良の方法は、自分でそれを実現させることです。よくコメントされたコードをデバッグさせます。適切なコメントがどのように見えるかを示します。コメントは、実際に関連情報を伝えない限り役に立ちません（通常は「理由」です。コードは「内容」を記述するためです）。彼らはそれがどれほど簡単か気づくでしょう。次に、古いコードの一部に戻らせます。彼らはそれがどれほど難しいかに気付くでしょう。あなたは彼らにすべきでないことだけでなく、何をすべきかを示しました（これはより重要です）。これ以上する必要はありません。さらに、口頭で説得する必要はありません。彼らは単に、独自の方法でコードをコメントする必要性を理解しなければなりません。これはもちろん、コメントする必要があるコードが自明ではないことを前提としています。

他のヒント

「なぜ」とだけコメントする; 「何」ではありません。これまでのところ、クラスまたはメソッドまたは変数名から、それが何をし、何に使用されているかを明確にする必要があります。コメントするのではなく、リファクタリングします。

このアプローチをとると、コメントが得られ、有用なコメントが得られます。プログラマーは、なぜ彼らが何かをしているのかを説明したい。

6か月前から独自のコードを見せます。彼らが2〜4分以内にそれが何をするのかを正確に理解して概要を説明できない場合は、おそらくあなたの指摘がなされている。

私の意見：

私はしません。メソッド/クラス名は、それが何をするかを言う必要があります。そうでない場合、メソッドまたはクラスのいずれかがやりすぎているか、名前が不適切です。

私は、なぜではなく、なぜコメントするのが好きです。コードが別のアプローチよりも1つのアプローチを使用している理由が明確でない場合は、コメントしてください。コンパイラのバグを回避するために未使用のハック変数を追加する必要がある場合は、理由をコメントしてください。ただし、＆quot; // Connect to database＆quot;などのコメントは、不正なコードまたは不正なポリシーの兆候です。 ConnectToDatabase（）という名前のメソッドの方がはるかに優れています。＆quot; // Determine DB server IP＆quot;がある場合その中で、おそらくそれを＆quot; DetermineDbServerIPAddress（）＆quot;という名前のメソッドに引き出す必要があります。

デザインは文書化できますが、コメントは一般的にそのレベルの文書化には適していません。設計に関する知識と、その理由についてのコメントがあれば、その内容と方法は明らかです。そうでない場合は、コードをコメントするように説得するのではなく、改善してもらいます。

おそらく、それは単なる経験から学ばなければならないものです。具体的には、6か月後に自分のコードに戻って、それを書いたときに何を考えていたのか（または何をしていたのか）を解決しようとする経験。それはコメントがそれほど悪い考えではないことを私に確信させました。

リファクタリングするために、いくつか（最低500行）の恐ろしい、コメントのないスパゲッティコードを提供します。変数に論理的な名前が付けられていないことを確認してください。空白はオプションです。

そして、どのようにそれらが好きかを見てください！

非常に過酷ですが、一度に2つのポイントを獲得します。

コードを適切に作成します。
コメントして、 その他 の意味がわかるようにします。

私は、このコードがそれらから発生したものではないことを強調する必要があります。コメントは、数か月先の自分のコードを理解するのに非常に役立ちますが、他の人のコードの複雑な部分を理解するためにも必要不可欠です。彼らは他の誰かが彼らが何をしているかを理解しなければならないかもしれないことを理解する必要があります。

最後の編集：コメント quality も非常に重要です。一部の開発者は、作業でコードとコメントの比率がほぼ2：1ですが、それでも良いコメントにはなりません。コードに驚くほど少数のコメントを含めることができ、それでもかなりの意味を持たせることができます。

何をしているのか説明します。あなたのコード品質は、この作業のほとんどをあなたのために行うべきです。
さらに重要なことは、何かをしている理由を説明することです！開発者（残念ながら私はほとんどの場合）がそもそもそれが良いアイデアだと思った理由がわからないまま、何かが何をしているのかを正確に示すコードを見てきました。

コードを読むことで、コードがすることだけを伝えることができ、想定されることを伝えることはできません。

あなたまたは他の開発者が Code Complete (またはコードコンプリート 2）それでも、今やっていることを止めて読んでください。

際立っているのは、「関数は 1 つのことだけを実行し、それを適切に実行する必要がある」ということです。そのような関数が、それがうまく機能する 1 つのことにちなんで名付けられている場合、さらにコメントする必要がありますか?

コメントには、記述しているはずのコードと同期が取れなくなる傾向があります。最初から元のコメントがない場合よりも悪い結果になる可能性があります。それだけでなく、開発者も知るコメントは古くなる可能性があり、信頼できないということです。したがって、彼らはコードを読んで、とにかくそれが実際に何をしているのかを自分で識別するでしょう。これでは、そもそもコメントを配置する意味が無効になります。

関数名にも同じことが当てはまりますが、元々は適切な名前が付けられていたかもしれませんが、名前ではほのめかされていない新しい操作が時間の経過とともに関数に追加されています。

すべてのコメントは、開発者が画面全体により多くの内容を表示できるように、近くに配置したいコード行を分離しているようです。私は、理解しなければならないコメントがたくさんあるコードに対する自分自身の反応を知っています。すべてのコメントを削除します。ここで、コードが何をしているのかがわかります。

一日の終わりに時間を過ごすなら 物事を正しくする ただコメントを書くよりも、コードが可能な限り適切に自己記述的であることを保証するためにコードをリファクタリングすることに時間を費やす方がはるかに有効です。このような練習は、コードの共通部分を特定するなど、他の方法でも役に立ちます。

また、多くの優秀な開発者は、あらゆる仮定や曖昧さがあるはるかに精度の低い人間の言語よりも、鮮明できれいな C# や Java などを書くことを好むことも心に留めておく価値があります。確かに、常識のあるほとんどの人は、どの程度の詳細が十分な詳細であるかを知っていますが、優れた開発者は「ほとんどの人」ではありません。だからこそ、私たちは次のようなコメントをしてしまうのです。 \\adds a to b and store it in c （極端すぎますが、要点はわかります）。

彼らがやりたくないこと、率直に言ってあまり得意ではないことを彼らに頼むのは（たとえそれが正しいことだと確信していても）、すでに負けた戦いにすぎません。

私はあなたをsしているわけではありませんが、質問を言い換えて、他の開発者にチームとして働くよう説得する必要がありますか

真剣に、一部の人々はあなたが彼らの心を読むことができると思います。

アジャイルチームの一員である場合、コードは集合的に所有されるため、コメントが付いていない、扱いにくい、または読みにくいコードを見つけた場合は、理解してコードを変更（リファクタリング）してください。人々が文句を言うなら、彼らにその理由を伝え、前もって話してください。あなたがそれを理解できないこと、そして誰もコードを所有していないことを発見した。

当社の戦略は、体系的なコードレビューを行い、適切に文書化されていないコードを拒否することです（コメント、適切な関数の命名、編成などを通じて）。レビュー担当者に明確でない場合は、作業台に戻ります。

昨日、あなたのコードを読む必要がありました。私はそれを理解することはできましたが、目標をどのように達成したかを説明する5行以下の適切なコメント行で、約1/10の時間でそれを読むことができ、その後、私は理解することを心配できました代わりに問題。私は愚かではありません、そしてあなたは理解するのが難しいことを書くことができるのであなたは賢くありません。逆に、読みやすいドキュメントとコードのアンサンブルを作成できない場合は、開発者ではありません。＆quot;

私はこれをずっと前に掘り下げました。何かを書いて、合理的な能力のある人がそれを理解できないなら、それはあなたのせいであり、彼のせいではありません。これは自然言語での記述に適用され、プログラミング言語での記述にも適用されます。

コメントについても同様の議論がありました。コードをコメントするときに人々が従うルールに関するものは次のとおりです：「ハードルール」とは何ですかコードのコメントについて。回答の中には、コードにコメントしたい理由も非常にあります。

コメントを求めて知恵を示してください。コメントを聞く可能性が高くなります。

より少ない。

量よりも品質を重視する。

私のチームでは、特定のAPIのすべてをコメントするプッシュがありました。一部の開発者は、メソッド名とシグネチャを確認してコメントを自動的に生成するツールを使用し始めました。

例：

/// <summary>
/// Gets the Person.
/// </summary>
/// <returns>
/// A Person
/// </returns>
public Person GetPerson()
{

}

スクリーンの不動産の大きな浪費を考えることができますか？新しい情報を提供しないコメントを読むよりも、脳のサイクルの無駄が大きいと思いますか？

メソッドのシグネチャから明らかな場合は、言わないでください！数秒で理解できる場合は、コメントに入れないでください。他の人が言っているように、あなたがやったことではなく、そのように選んだのはなぜか教えてください。コードが何をするのか明白になるように記述してください。

模範を示してリードしましょう。開発者は「正しいこと」を見ると簡単に動揺するため、実際に確実な実践が行われているのを見ると、同じように行動するようになる可能性があります。さらに、コードの保守性とコメントに対処するコードメトリクスを採用するようグループに奨励することもできます。たとえば、コード分析では、概要ドキュメントのないメソッドに対してバグが発生します。

私の現在の職場での現在のコーディング標準は、すべての機能についてコメントすることです。このような空白のルールは有害であり、絶対に使用しないでください。コメントを追加すると読みにくくなる場合があります（その一部は一般的です）。

class User {
    getUserName() { /* code here */ }
}

上記のコードに関数ヘッダーを追加する意味は何ですか？他に何を言いますか？「ユーザー名を取得します」。すべてのコードにコメントを付ける必要はありません。私の経験則では、関数シグネチャにはない有用な情報を追加していない場合はコメントをスキップします。

コメントは徹底的で、意図のレベル（理由ではない）で記述されており、まれであるべきです。

コードを書くとき、当然のこととしてかなり合理的にコメントする傾向があります。次に、コードを理解しやすくすることなく、できるだけ多くのコメントを削除してみます。＆gt; 80％の場合、これは適切な名前のメソッドを抽出するのと同じくらい簡単です。これは通常、コード自体の情報を複製するだけのコメントになります。それを超えて、「必要」なコードのセクションがある場合コメントを簡素化または明確にする方法を探しています。

コードは自己文書化し、正しいテクニックを使用して、そこにある方法の95％をかなり簡単に取得できます。一般に、チェックインするコードにコメントが残っている場合は失敗と見なします。

お持ちのパワーに依存します...

非常に効果的な方法は、ピアベースのコードレビューの固定部分にすること、つまりコメントのポイントにすることです。コードが不適切にコメントされているという発言があった場合、私は開発者に満足のいくコメントをさせます。そして、私もそれをします。

驚くべきことに、これはディケンズのように聞こえますが、開発者に人気がありました。 2つのことが起こりました。まず、人々は自分のコードにコメントし始めました。第二に、不適切にコメントされたコードは、開発者が自分が書いたものをよく理解していないというサインになりました（そうでなければ、彼らはそれを説明していたでしょう）。

唯一の本当の欠点は、バグ修正などのために修正されたときにコメントがコードに遅れないようにしなければならないことでした。自然に起こりました。

ところで、ドストエフスキーの小説ではなく、文字列としてのコード自体のコメントを好みます。前者は、その後のプログラマーにとって有用な補助です。後者は、ドキュメントを埋め尽くし、すべての人を誤解させる古いテキストの単なる長い断片です。

馴染みのないAPIを使用するようにしますが、APIのドキュメントにアクセスできないように、インターネットに接続されていないマシンでプログラミングを行います（最近見つかった場合）。これは、ドキュメント化されていない人のコードを使用しようとする場合に、他の開発者に強制することです。

ここでは、2つの異なるコメントを区別する必要があります：

APIコメント（javadocまたはその他の同様のドキュメント）： 制限シナリオで独自のコードを使用 （nullオブジェクトや空の文字列などの境界条件または...）そして彼らが実際にそれらの場合に自分の機能を何を覚えているかを確認します
（だから私は limit-valueを含む完全なjavadoc を求めています）
内部コメント（ソースコード内）：コーディングした機能を説明するように依頼することができます。 本当にサイクロマティックの複雑度が高い すべての異なるコードワークフローと意思決定分岐の周り;）

さて、常に「あなたのコードにコメントをしないと、彼らのコードにコメントする誰かを見つける」というものがあります。アプローチ。

もっと穏やかに、彼らが彼らがしていることを文書化してコメントしなければ、彼らはひどくチームを失望させていると彼らに伝えてください。完全に孤立したオオカミでない限り、コードは個人に属しません。それは会社であれコミュニティであれ、チーム、グループに属します。

＆quot;コードの記述＆quot; =＆quot;特別な言語でのコマンドのシーケンス＆quot; +＆quot;コメントの作成＆quot;

コードを書いている間にコードをコメントすることは自明のことです！すでに3か月または4か月前のコードにコメントしたことはありますか？（もちろん、あなたは持っており、それは楽しい以外のすべてでした！）

プロジェクトがすでに十分に文書化されている場合、新しいコードを追加するプログラマは、同様の方法でコメントを書くように動機付けられる可能性があります。

@James Curran 100％賛成です！私はあなたのコードを読んで、あなたがコンパイラに何をするように言ったかを理解できます。しかし、それはコンパイラーにそれをさせる意図であったという意味ではありません。私は、コードを書くたびにそれをやろうとしていたことを正確に行うと信じるほど慢なプログラマーではないことを知っています。さらに、コードを書いた後、コードの目的を説明しようとすることで、コードの愚かな論理エラーをキャッチするのに役立つことがよくあります。

1つのアイデアは、クラスごとに1つまたは2つの文を記述するのに1分未満、メソッドごとに1つの文を記述するのに30分未満かかることを指摘することです。

機能とJavadocコメントとのインターフェースをドキュメント化し、Doxygenを介してコードを実行し、コードの見栄えの良いHTMLドキュメントを生成するように伝えます。クールネスファクターは、時には良い動機付けになります。

微妙なテクニックを1つ使用しています：

エラーとして報告されるプロジェクトの警告レベルを設定します。そして、当社の継続的インテグレーションサーバーは、各ドキュメントにXMLドキュメントとともにソリューション全体を構築しています。

開発者がコメントを書かないと、ビルドは失敗します！そしてその後、彼らはコメントを書かなければならないので、しばらくして、彼らはそれに慣れました。

プレッシャーに関しては積極的ではありませんが、彼らの行動を修正する良い方法のように思います。

開発者がコードレビューに参加する必要があり、良いコメントにさらされている場合、開発者は手がかりを得ることができるはずです。プラクティスが有用であると思わない場合は、ピアレビューアからフィードバックを受け取る必要があります。

それに失敗した場合（あなたがスーパーバイザー/マネージャーであると仮定）、パフォーマンス評価の一部にします。測定できる場合は、それに基づいて評価できます。

受動的な攻撃的な開発者は、最後のすべてのステートメントをそれほど微妙ではないFUとして文書化するため、あなたが採点するのはレビュー済みのコメントであることを確認してください。

私は、 Headrick's Rule と呼ばれるものを固く信じています。誰かが何かをやる気にさせる良い方法は、彼らを苦しめることだということを発見した私の同僚の名前です。 em>しない。

あなたの場合、コメントしていない開発者にコードを説明するのに1時間か2時間を費やすように依頼します。オーディエンス、おそらく昼食時間中に「プロジェクトのずれを避けるため」長い道のりを歩みます。頭のいい人でも、頑固な人でも、早く学べます！

私の意見では（そしてここで.Netプログラミングについて話しています）、コメントを付けなければならない場合、コードを読みやすくすることに失敗しました。答えは通常リファクタリングです！

ただし、コメントを入力する必要があると感じた場合は、常に「理由」を指定する必要があります。コードの機能を説明するコメントではなく、コメントのタイプ。

実際にコーディングする前にメソッド/クラスが何をするかを書き留めることは、それを正しくするのに大いに役立ちます-あなたはそれをコメントしました。

コードに意図を暗黙的に述べることを保証する優秀なエンジニアのみを採用します（コメントなどを使用）。仕事をしたい人は誰でも正しくやらなければなりません。厳しい、しかし公平、私見。

ライセンス： CC-BY-SA と帰属

所属していません StackOverflow