コメントでトートロジーに対処する方法は？[閉まっている]

時々、私が書いているコードの一部が、その名前が基本的にコメントとして繰り返されることを自明である（またはそうであるように思われる）状況に自分自身を見つけます：

class Example
{
    /// <summary>
    /// The location of the update.
    /// </summary>
    public Uri UpdateLocation { get; set; };
}

（C＃の例ですが、質問は言語に依存しないようにしてください）。

そのようなコメントは無意味です。私は何を間違えていますか？間違っているのは名前の選択ですか？このような部分をより良くコメントするにはどうすればよいですか？このようなことに対するコメントをスキップする必要がありますか？

私が取り組んでいるほとんどのプロジェクトでは、クラスメンバー全員に詳細なコメントを書く時間はあまりありません。

それはコメントの時間がないという意味ではありません。それどころか、コメントされているものの言い換えられたバージョンを吐き出すトートロジーのコメントには十分な時間があります。彼らは出発点としてうまくいきます。

特にVisual StudioがIntelliSenseに付随するコメントを使用していることを考えると、フィールドに関する短い情報から始めることをお勧めします。

class Example
{
    /// <summary>
    /// The location of the update.
    /// </summary>
    public Uri UpdateLocation { get; set; };
}

そして、コードの作成を続けると、更新が行われた場所であったか、更新が送信された場所であったかを思い出せない場合UpdateLocation、コードを再検討する必要があります。この時点で、追加情報を追加する必要があります。

class Example
{
    /// <summary>
    /// The Uri location where the update took place.
    /// </summary>
    public Uri UpdateLocation { get; set; };
}

別のプログラマがフィールドの詳細について尋ねてきた場合は、その情報でコメントを更新してください。

Example.UpdateLocation保存にはどのような更新を使用する必要がありますか？

class Example
{
    /// <summary>
    /// The Uri location where the Foo update took place.
    /// </summary>
    public Uri UpdateLocation { get; set; };
}

プログラムにバグがあるのと同じように、良いコメントには反復的に修正する必要があるバグがあります。コメントの目的は、6か月後にコードを再訪し、プログラムの動作について何も思い出せない場合に、コードの理解を支援することです。

プログラミングと同じように、コメントはどこかから始めなければなりません。トートロジーコメントはHello World!コメントです。ドキュメントの作成と更新を練習するにつれて、開始ドキュメントはますます回復力が増します。

コメントでコードを複製しないでください。コメントは「how？」という質問には答えず、「why？」と「what？」だけに答えるべきです。そのようなアルゴリズムが選ばれる理由、ここでの暗黙の仮定は何ですか（あなたの言語が型システム、コントラクトなどでそれを表現するのに十分強力でない限り）、このことを行う理由は何ですか、など

インスピレーションを得るには、Literate Programmingの実践をご覧になることをお勧めします。

コメントはコードを説明するものであり、複製するものではありません。このヘッダーコメントは重複しています。はなれる。

それらを省いてください！

通常、コメントで表現された情報がすでに他の場所にある場合は、コメントを削除することをお勧めします。メソッドに適切な名前を付けることで、メソッドの目的を明確かつ明確に表現できれば、コメントは不要です。

入れて！

例では、このルールの2つの例外を示しています。

まず、「UpdateLocation」は（コンテキストに応じて）あいまいになる場合があります。その場合、より良い名前を付けるか、コメントを入力してあいまいさを解消する必要があります。一般的に、名前を改善する方が良い選択肢ですが、これは常に可能とは限りません（たとえば、公開されたAPIを実装する場合）。

第二に、C＃の「///」は、ドキュメントの自動生成に使用することを意図したコメントを示します。IDEはこれらのコメントをツールチップに使用し、これらのコメントからヘルプファイルなどを生成できるツール（サンドキャッスル）があります。そのため、ドキュメント化するメソッドにすでに説明的な名前が付いている場合でも、これらのコメントを挿入するための引数があります。しかし、それでも、多くの経験豊富な開発者は、情報の重複に眉をひそめていました。決定要因は、ドキュメントの対象者のニーズである必要があります。

「コメントを書かない」という回答には強く反対します。どうして？あなたの例を少し変えて指摘させてください。

public Uri UpdateLocation ();

それで、この関数は何をしますか：

• 「更新場所」を返しますか？または
• 場所を「更新」して新しい場所を返しますか？

コメントなしではあいまいさがあります。新規参入者は簡単に間違いを犯す可能性があります。

あなたの例では、プロパティであるため、「get / set」メソッドは2番目のオプションが正しくないことを明らかにし、実際には「場所の更新」ではなく「場所の更新」を意味します。しかし、特に「更新」などのあいまいな単語の場合、この間違いを犯すのは非常に簡単です。安全にプレイしてください。数秒の時間を節約するためだけに、これに不慣れな人を混同しないでください。

/// <summary>ブロックは、IntelliSenseおよびAPIドキュメントのドキュメントを生成するために使用されます。

したがって、これが公開APIである場合、関数の目的が読者に自明である必要がある場合でも、少なくともコメントを常に含める必要があります。<summary>

ただし、これはルールの例外です。一般に、DRY （Do n't Repeat Yourself）を忘れないでください。

このようなコメントを入力するのは、そのようなものからどのようなメリットがあるかを知っている場合のみにしてください。それ以外の場合は、それらを拭いてください。

_{私にとっての場合、明確な利点があり、コメントを逃すための自動化されたチェックしたときだったと私は、重要な情報が満たされるために必要なコードを検出するために、そのチェックを使用していました。このため、私は確かにいくつかのプレースホルダーを埋めていました-ツールレポートに「誤ったアラーム」が含まれないようにするためです。}

露骨な重複を避ける方法は常にあると思います。長年にわたり、私はあなたのような場合にカップルの「テンプレートフィラー」を使用するようになりました-主に自己記述的な名前と上記を参照してください。

この特定の例では、次のような「自己記述型」の何かを使用します（ワイプアウトがジョブを実行する場合ではないことを前提としています）。

class Example
{
    /// <summary>
    /// Self descriptive method name.
    /// </summary>
    public Uri UpdateLocation { get; set; };
}

_{上記の種類のフィラーを使用できる場合の例は、戻り値、パラメーター、および例外用の専用フィールドを必要とするJavadocコメントです。かなり頻繁に、これらのほとんどまたはすべてを単一の要約文で提供する方が理にかなっていることがわかります。提供されたパラメーター<describe parameters>に対して<describe what>を返すメソッドです。そのような場合、正式に必要なフィールドに上記の単純な説明を記入し、読者に概要の説明を示します。}

コードのセクションにコメントを追加するかどうかを考えるときに私が自問したい質問があります：次の人がコードの全体的な意図をよりよく理解し、更新、修正、またはより速く、より確実に拡張しますか？

この質問に対する正しい答えは、コードのその時点で追加できるものはほとんどないということです。これは、意図をできるだけ明確にする名前と規則を既に選択しているためです。つまり、堅実な自己文書化コードを作成し、そこにコメントを挿入すると、役に立つよりも多くを損なう可能性が高いことを意味します。（冗長なコメントは、時間の経過とともに実際のコードとの同期が遅くなり、実際の意図を解読しにくくすることで、時間の経過とともにコードの信頼性を実際に損なう可能性があることに注意してください。

ただし、ほとんどすべてのプログラムおよびプログラミング言語では、元のプログラマー（ユーザー）によって行われた特定の重要な概念と決定がコードに現れなくなるポイントに遭遇します。優れたプログラマーは常に将来のためにプログラムするので、これはかなり避けられません-つまり、プログラムを一度だけ動作させるだけでなく、その多くの将来の修正、バージョン、拡張、修正、移植をすべて行い、誰が何をすべきかを知っているためですまた、正常に動作します。後者の一連の目標は非常に難しく、うまくいくためにはもっと多くの思考が必要です。つまり、何を言って上-機能のより集中しているほとんどのコンピュータ言語でうまく表現することも非常に難しいです、これを プログラムのバージョンは、満足のいくものにするために、今すぐ行う必要があります。

ここに私が言っていることの簡単な例を示します。ほとんどの言語では、小さなデータ構造の迅速なインライン検索には十分な複雑さがあり、初めてそれを見る人は、それが何であるかをすぐには認識しないでしょう。これは良いコメントの機会です。なぜなら、コードの意図について何かを追加することができ、後の読者が詳細を解読するのに役立つとすぐに感謝するでしょう。

逆に、ロジックベースの言語Prologのような言語では、小さなリストの検索を発現することを信じられないほどつまらないと簡潔できる任意の追加かもしれないコメントだけでノイズだろう。したがって、適切なコメントは必ずコンテキストに依存します。これには、使用している言語の長さやプログラム全体のコンテキストなどの要因が含まれます。

一番下の行はこれです：未来を考えてください。プログラムが将来どのように理解され修正されるべきかについて、あなたにとって重要かつ明白なことを自問してください。[1]

本当に自己文書化されているコードの部分については、コメントはノイズを追加し、将来のバージョンの一貫性の問題を増やします。そこで追加しないでください。

ただし、いくつかのオプションから重要な決定を下したコードの部分、またはコード自体が目的があいまいになるほど複雑な部分については、コメントの形で特別な知識を追加してください。このような場合の良いコメントは、将来のプログラマーに、何を同じに保つ必要があるか、つまり、不変のアサーションの概念であるが、何を変更してもよいかを知らせるものです。

[1]これはコメントの問題を超えていますが、提起する価値があります。コードが将来どのように変更されるかについて非常に明確な考えを持っていることがわかった場合は、コメントを作成してそれらのパラメーターを埋め込むだけでなく、おそらく考えるべきですコード自体の中で、コメントを使用して未知の未来の人を正しい方向に導くよりも、コードの将来のバージョンの信頼性を確保するためのほとんどの場合、それはより信頼できる方法です。同時に、人間は未来を予測することで悪名が高く、これにはプログラム変更の未来が含まれるため、一般化を避けることも必要です。そのため、プログラム設計のすべてのレベルで、将来の合理的で実証済みの側面を定義してキャプチャしようとしますが、

私自身のコードでは、次のような特に悪質なものを含め、コメントのトートロジーを頻繁に残しています。

<?php
// return the result
return $result;
?>

...これは明らかに、コードを説明の観点からよりわかりやすくするという点ではほとんど貢献していません。

しかし、私の考えでは、これらのコメントは、構文ハイライターのカラーパターンの視覚的な一貫性を維持するのに役立つ場合、依然として価値があります。

「文」と「段落」があるという点で、コードは英語に非常に類似した構造を持っていると考えています（「段落」は完全に単一の「文」で構成されている場合でも）。通常、各「段落」の上に改行と1行の要約を含めます。例えば：

<?php
//get the id of the thing
$id = $_POST['id'];

//query the things out of the the database
$things = array();
$result = mysql_query("SELECT * FROM Things WHERE `id` = $id");
while ($row = mysql_fetch_assoc($result)) {
    //create a proper Thing object or whatever
    $things[] = new Thing($row);
}

//return the things
return $things;
?>

（不完全なコード、SQLインジェクションなどは無視してください。アイデアが得られます。）

私にとって、最後のコメントはコードに真に価値を追加します。一貫性のある配色を維持することで、ある「段落」を別の「段落」から視覚的に描くのに役立つからです。

コメントは、次のいずれかを行うために使用する必要があります。

1. 取得するドキュメントジェネレーターの情報。控えめに言っても、これは非常に重要です。
2. なぜコードがそのようになっているのか、その他の考慮事項についての警告。2つのプログラミング言語で書かれたコードを扱ってきました。これの重要な部分の1つは、2つの言語に共通の構造を持たせることでした。この番号を変更した場合、別の番号も変更する必要があることをユーザーに知らせる両方の場所でのコメントは非常に役立ちます。
3. 特に奇妙に見えるコードがそうである理由を説明するメモを書いてください。特定の方法でコードの一部を動作させる方法を考えなければならず、解決策が最初から明らかでない場合は、おそらくあなたが何をしようとしているかについて説明する価値があります。
4. 明確でない場合は、入力/出力のラベル付け。入力がどのようなもので、どのような形式になっているのかを知ることは常に良いことです。

コメントを使用して以下を実行しないでください。

1. 非常に明白なことを説明します。私はかつてこのようなレガシーコードを見ました：page=0; // Sets the page to 0。有能な個人なら誰でもそれを理解できると思います。

トートロジーを削除しますが、コメントを保持し、サンプル値を指定してプロパティと変数名をコメントし、使用法が明確に理解されるようにします。

property UpdateLocation:TUpdateLocation;  // url="http://x/y/3.2/upd.aspx",proto=http

今、私はそこに何が入っているかを正確に知っており、コメントから、それをどのように使用するか明確なアイデアを持っています。

コメントの目的によると思います。

それらを使用して、それを構築するチームが使用するドキュメントを生成する場合（または、物事を説明するための単なるインラインコメントである場合）、それを省略してもかまいません。自明であると安全に想定できます。そうでない場合は、近くに説明できる他のチームメンバーがいます。もちろん、多くの人にとって自明ではないことが判明した場合は、追加する必要があります。

コメントが地理的に離れたチームのドキュメントを生成する場合は、そこにあらゆるドキュメントを配置します。

このトピックは、「コメント：アンチパターン」や「コメントはコードにおいですか？」などの名前でかなり広範囲に議論されていると思います。（1つの例）。

私は、コメントは複製ではなく、新しい情報を追加すべきだという一般的な考えに同意する傾向があります。そのようなささいなコメントを追加することにより、DRYに違反し、コードの信号対雑音比が低下します。プロパティのコメント（特に余分なコメント）よりも、クラスの責任、根拠、クラスの使用例を説明する高レベルのコメントがはるかに役立つ傾向があります。

個人的には、あなたの例では、コメントを省略します（プロパティについて追加するのに役立つものが本当にない場合）。

コメントを必要としないコードを書くことができれば、プログラミングのprogrammingを達成したことになります！

コードに必要なコメントが少なければ少ないほど、コードは良くなります！

そのようなコメントは無意味です。私は何を間違えていますか？

何をするのか既に知っている場合にのみ、役に立たないようですUpdateLocation。ここでの「更新」は動詞ですか、それとも名詞の補助詞ですか？つまり、これは場所を更新するものですか、それとも更新の場所ですか？UpdateLocation明らかにプロパティであるという事実から後者を推測するかもしれませんが、より重要なことは、明らかなことを明示的に述べることは害にならないことです。

自動コンパイルされたドキュメントは別として、コードはそれ自体をドキュメント化する必要があります。したがって、コメントは、コードがそれ自体をドキュメント化するのに十分でない場合にのみドキュメント化する必要があります。

「ロケーション」は一種の明らかですが、「更新」は少し曖昧かもしれません。あなたがより良い名前を書くことができないなら、あなたはコメントでより詳細を提供できますか？何の更新？なぜ私たちはこれが必要なのですか？いくつかの仮定は何ですか（null許容）？