コメントでトートロジーに対処する方法は？
私が書いているコードの一部が（またはと思われる）なので、その名前がコメントとして基本的に繰り返されることが自明であることもあります。
class Example
{
/// <summary>
/// The location of the update.
/// </summary>
public Uri UpdateLocation { get; set; };
}
（C＃の例ですが、質問は言語に依存しないものとして参照してください）。
そのようなコメントは無意味です。私は何を間違っていますか？間違っているのは名前の選択ですか？このような部分にコメントするにはどうすればよいですか？このようなコメントはスキップする必要がありますか？
私が取り組んでいるほとんどのプロジェクトでは、クラスのメンバー全員に詳細なコメントを書く時間はそれほど多くありません。
これは、コメントする時間がないという意味ではありません。それどころか、コメントされているものの言い換えたバージョンを吐き出すトートロジーのコメントには十分な時間があります。彼らは出発点として素晴らしい働きをします。
特に IntelliSense に付随するVisual Studioのコメントの使用法を考えると、フィールドに関する短い情報から始めることをお勧めします。
class Example
{
/// <summary>
/// The location of the update.
/// </summary>
public Uri UpdateLocation { get; set; };
}
そして、コードを書き続けると、whenUpdateLocationが更新が行われた場所なのか、更新が行われる場所なのかを思い出せませんに送信された後は、コードを再確認する必要があります。この時点で、その追加情報を追加する必要があります。
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!のコメント。ドキュメントの作成と更新を練習するにつれて、開始時のドキュメントの耐障害性はますます高まります。
コメントはneverコードを複製する必要があります。コメントは "how？"の質問に答えるべきではなく、 "why？"と "what？"のみに答えるべきです。なぜそのようなアルゴリズムが選択されるのか、ここで暗黙の仮定は何か（あなたの言語が型システムやコントラクトなどでそれを表現するのに十分強力でない限り）、これを行う理由は何ですか？.
インスピレーションを得るために、文芸プログラミングの実践をご覧になることをお勧めします。
コメントはdescribeコードである必要があります。重複してはいけません。このヘッダーコメントは重複しています。はなれる。
除外してください！
通常、コメントで示された情報がすでに他の場所に存在している場合は、コメントを削除することをお勧めします。メソッドに適切な名前を付けることにより、メソッドの目的を明確かつ明確に表現できる場合は、 コメントは不要 です。
入れてください！
この例は、このルールの2つの例外を示しています。
まず、「UpdateLocation」は（コンテキストによっては）あいまいになる可能性があります。その場合は、あいまいさをなくすために、より適切な名前を付けるか、コメントを提供する必要があります。一般に、名前を改善することをお勧めしますが、これが常に可能であるとは限りません（たとえば、公開されたAPIを実装している場合）。
次に、C＃の「///」は、ドキュメントの自動生成に使用することを目的としたコメントを示します。 IDEはこれらのコメントをツールチップに使用し、これらのコメントからヘルプファイルなどを生成できるツール（Sandcastle）があります。したがって、たとえこれらのコメントを挿入するための引数があります。彼らが文書化するメソッドには既に説明的な名前が付いていますが、それでも多くの経験豊富な開発者は情報の重複を避けます。決定的な要因は、文書化の対象となる人々のニーズです。
「コメントを書いてはいけない」という返答には強く反対します。どうして？例を少し変更して指摘しておきます。
public Uri UpdateLocation ();
したがって、この関数は何をしますか：
- 「更新場所」を返しますか？または
- 場所を「更新」して新しい場所を返しますか？
コメントがなければあいまいさがあることがわかります。新人は間違いを犯しやすい。
あなたの例では、それはプロパティなので、「get/set」メソッドは2番目のオプションが正しくないことを明らかにし、「場所の更新」ではなく「場所の更新」を意味します。しかし、特に「更新」などのあいまいな単語の場合には、この間違いを犯すのは非常に簡単です。安全にプレイしてください。あなたの時間の数秒を節約するためだけにこれに新しい人を混乱させないでください。
_/// <summary>_ブロックはIntelliSense およびAPIドキュメントのドキュメントを生成するために使用されます。
したがって、これが公開APIである場合は、関数の目的があるべき自己であっても、少なくとも_<summary>_コメントを含める必要がありますalways読者には明らかです。
ただし、これはルールの例外です。一般に、 [〜＃〜] dry [〜＃〜]（Do n't Repeat Yourself）を忘れないでください。
そのようなコメントを記入してくださいifそのようなものからどのように役立つかを知っている場合のみ。それ以外の場合は、それらを拭いてください。
私にとって、明確な利点のケースは、コメントの欠落に対する自動チェックがあったときであり、そのチェックを使用して検出していた重要な情報を入力する必要があるコード。このため、私は実際にいくつかのplaceholdersを入力していました。これは、ツールレポートに「誤ったアラーム」が含まれていないことを確認するためです。
露骨な重複を避けるへの道は常にあると思います。長年にわたって、私はあなたのような場合にカップルの「テンプレートフィラー」を使用するようになりました-ほとんどが自己記述的な名前と上記を参照のようなものです。
この特定の例では、次のように「自己記述的な」種類のものを使用します（ワイプで削除できるわけではない場合）。
class Example
{
/// <summary>
/// Self descriptive method name.
/// </summary>
public Uri UpdateLocation { get; set; };
}
上記を参照種類のフィラーを使用できる場合の例は、戻り値、パラメーター、および例外用の専用フィールドを必要とする Javadoc コメントになります。かなり頻繁に、これらのほとんどまたはすべてを単一の要約文で説明する方が理にかなっていることがわかります提供されたパラメーター<describe parameters>に対して<describe parameters>を返すメソッド。そのような場合、私は正式な必須フィールドにプレーンな上記を参照を入力し、読者に概要の説明を示します。
ここに、コードのセクションにコメントを追加するかどうかを検討する際に自問したい質問があります。次の人がコードの全体的な理解を深めるために何が伝わるでしょうかintent彼らはそれをより速く、より確実に更新、修正、または拡張できますか？
この質問に対する正しい答えは、コードのその時点で追加できるものはほとんどないという場合があります。それは、意図をできるだけ明確にする名前と規則を既に選択しているためです。つまり、しっかりした自己文書化コードを書いていて、そこにコメントを挿入すると、それが役立つよりも害を及ぼす可能性が高いということです。 （冗長なコメントは、時間の経過とともに実際のコードとの同期からの脱落が遅くなり、実際の意図を解読することが難しくなるため、時間の経過とともに実際にコードの信頼性を損なう可能性があることに注意してください。
ただし、ほとんどすべてのプログラムおよびすべてのプログラミング言語で、元のプログラマーによって（ユーザーによって）行われた特定の重要な概念および決定がコードで明らかにされなくなる点に遭遇します。優れたプログラマalways将来のためのプログラム-つまり、プログラムを一度だけ動作させるだけでなく、将来の多くの修正、バージョン、拡張機能、修正をすべて行うため、これはかなり避けられません。そしてポートと誰がalsoが正しく機能するかを知っています。後者の一連の目標は非常に困難であり、うまくいくにはもっと多くの思考が必要です。また、機能に重点を置いているほとんどのコンピュータ言語でうまく表現することも非常に困難です。つまり、プログラムのバージョンthisが今何をする必要があるのかということです。それを満足させる。
これが私が意味することの簡単な例です。ほとんどの言語では、小さなデータ構造の迅速なインライン検索は、初めてそれを見る誰かがそれが何であるかをすぐに認識しない可能性が高いほど複雑になります。コードのintentについて何かを追加することができるので、これは良いコメントの機会です。詳細を解読するのに役立つと後の読者はすぐに理解するでしょう。
逆に、ロジックベースの言語Prologなどの言語では、小さなリストの検索を表現するのは非常に簡単で簡潔なので、追加する可能性のあるanyコメントは単なるノイズになります。したがって、適切なコメントは必ずコンテキストに依存します。これには、使用している言語の長所やプログラム全体のコンテキストなどの要素が含まれます。
肝心なのはこれです。未来を考えてください。プログラムをどのように理解し、将来的に変更する必要があるかについて、何が重要で明白かを自問してください。[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インジェクションなどは無視してください。アイデアがわかります。）
私にとって、最後のコメントはコードに真の価値を付加します。それは、一貫したカラースキームを維持することによって、ある「段落」を別の段落から視覚的に区別するのに役立つからです。
コメントは、次のいずれかを行うために使用する必要があります。
- ドキュメントジェネレータが取得する情報。これは控えめにすることはできません。これは非常に重要です。
- コードの一部が現状のままである理由、およびその他の考慮事項に関する警告。私は2つのプログラミング言語で書かれたコードを扱いました。これの重要な部分は、2つの言語間で共通の構造を持つことでした。この番号を変更した場合、別の番号も変更する必要があることをユーザーに通知する両方の場所でのコメントは、非常に役立ちます。
- 特に奇妙に見えるコードの断片がなぜそのようになっているのかを説明するメモを書きます。コードを特定の方法で機能させる方法を考える必要があり、解決策が最初から明らかでない場合は、何をしようとしていたのかを説明する価値があります。
- 入力/出力に明確でない場合のラベル付け。入力がどのようなものであると予想され、どのような形式であるかを知ることは常に良いことです。
コメントは、次のことを行うために使用しないでください。
- 非常に明白なことを説明します。私はかつてこのようなレガシーコードを見た：
page=0; // Sets the page to 0。私はどんな有能な個人でもそれを理解できると思います。
トートロジーは削除しますが、コメントは残します。使用法が明確に理解できるように、サンプル値を指定してプロパティと変数名にコメントを付けます。
property UpdateLocation:TUpdateLocation; // url="http://x/y/3.2/upd.aspx",proto=http
そこに何が入っているのか正確にわかったので、コメントから、それをどのように使用するかが明確にわかります。
そのようなコメントは無意味です。私は何を間違っていますか？
UpdateLocationが何をするかを既に知っている場合にのみ、役に立たないようです。ここでの「更新」は動詞か名詞の補助ですか？つまり、これは場所を更新するものですか、それとも更新の場所ですか？ UpdateLocationは明らかにプロパティであるという事実から後者を推測するかもしれませんが、より大きなポイントは、明白であると思われるものを明示的に述べることは時には害にならないということです。
自動コンパイルされたドキュメントは別にして、コードはそれ自体をドキュメント化する必要があります。そのため、コメントは、コードがそれ自体をドキュメント化するのに十分ではない場所のみをドキュメント化する必要があります。
コメントの目的次第だと思います。
それらを使用して、それを構築するチームが使用するドキュメントを生成する場合（または、説明するためのインラインコメントのみの場合）、省略してもかまいません。それは自明であると安全に想定することができます。そうでない場合は、近くに他のチームメンバーが説明してくれます。もちろん、多くの人にとって自明ではないことがわかった場合は、追加する必要があります。
コメントが地理的に離れたチームのドキュメントを生成する場合、そこにすべてのドキュメントを配置します。
このトピックは、「コメント：アンチパターン」や「コメントはコードの匂いですか？」 （ 一例 ）。
コメントは新しい情報を追加するのではなく、追加するべきだという一般的な考えに同意する傾向があります。そのような些細なコメントを追加することで、DRYに違反し、コードのS/N比が低下します。プロパティごとのコメント（特に余分なコメント）よりもはるかに役立つ、責任、背後にある根拠、およびクラスの使用例を説明する高レベルのコメントを見つける傾向があります。
個人的には、あなたの例では、コメントを残します（プロパティについて本当に何も追加する必要がない場合）。
コメントを必要としないコードを書くことができれば、プログラミングニルヴァーナを達成したことになります！。
コードのコメント数が少ないほど、必須コードが優れています！