10

誰かがあなたの意図を理解するのに十分なコメントをいつ書いたかを判断するのが本当に難しい場合があります.

何が起こっているのかを詳細に説明する大量のコメント行を含めるよりも、読みやすく理解しやすいコードを書くことにもっと集中する必要があると思います。

これについてどう思いますか？

4

13 に答える 13

30

コメントは、あなたが何をしているのかを説明するものではありません。彼らはあなたがそれをしている理由を説明するためにそこにいます。

于 2009-02-13T13:37:51.720 に答える
12

この議論は誤ったジレンマに基づいています: あなたのコードは恐ろしい忌まわしきものであり、すべてのステートメントと式を説明するために大量のコメントを書いているか、それともあなたのコードはドキュメントがまったくなくても祖母が理解できる美しい詩です。

実際には、後者を目指して努力する必要があります (おばあさんではなく、他の開発者かもしれません) が、2、3 のコメントがあいまいさを解消したり、次の 10 行のコードを非常にわかりやすくしたりする場合があることを認識してください。まったくコメントしないことを主張する人々は過激派です。

もちろん、不当なコメントは避けるべきです。悪いコードをより理解しやすくするのに、コメントはいくらあっても役に立ちません。彼らはおそらくそれを悪化させるだけです. しかし、些細なシステムをコーディングするだけでない限り、コメントによって設計上の決定が明確になる場合があります。

これは、バグをキャッチするときに役立ちます。読み書き可能なコードは、完全に間違っているように見えても、完全に正当に見えることがあります。コメントがなければ、他の人 (または 6 か月後のあなた) があなたの意図を推測する必要があります。これはバグですか、それとも別の場所ですか? 設計ドキュメントを参照する必要があるかもしれません... コメントはインライン ドキュメントであり、必要な場所に表示されます。

コメントの必要性が実際にいつ存在するかを適切に判断することが重要です。

于 2009-02-13T13:51:35.413 に答える
5

コードを自明なものにするようにしてください。最も重要なことの 1 つは、クラス、関数、変数などに意味のある名前を使用することです。

自明ではないセクションにコメントしてください。些細なコメント (例: i++; // i に 1 を加える) は、コードを読みにくくします。

ところで、疑似コードに近づけば近づくほど、コードは自己説明的になります。これは高級言語の特権です。自明なアセンブリ コードを作成するのは困難です。

于 2009-02-13T13:41:50.383 に答える
2

すべてのコードが自己文書化できるわけではありません。

現在、パフォーマンスの問題のトラブルシューティングを行っています。開発者は、ボトルネックの原因を発見したと考えました。何らかの理由でスリープしようとしていたコードのブロック。このコードに関するコメントはなく、なぜそこにあったのかについてのコンテキストもありませんでした。ブロックを削除し、再テストしました。現在、アプリは以前にはなかった負荷の下で失敗しています。

私の推測では、誰かが以前にパフォーマンスの問題に遭遇し、このコードを挿入して問題を軽減していたのでしょう。それが正しい解決策であったかどうかは問題ではありませんが、なぜこのコードが存在するのかについてのいくつかのコメントは、私たちの苦痛と多くの時間を節約するでしょう...

于 2009-02-13T13:56:29.490 に答える
1

コメントが必要な理由。メソッドの名前は、コメントを必要としないほど明確にする必要があります。

元：

//  This method is used to retrieve information about contact
public getContact()
{
}

この場合、getContact はコメントを必要としません。

于 2009-02-13T13:54:06.283 に答える
0

基本的には、クラス/メソッド/関数の宣言の先頭に良いがおそらく短いコメントを置いておき、必要に応じてファイルの先頭に導入コメントを置いておくと、コメントはあまり一般的でない場合やあまり明確ではない操作がコード化されています。

したがって、たとえば、明らかなこと (前の例では i++;) にコメントすることは避けるべきですが、あまり明白でないことや、よりトリッキーなことについては、明確で、混乱がなく、見事で、完全なコメント行に値するはずです。歴史上最も明確なコードに対してノーベル賞を受賞しました ;)。

そして、コメントも面白いものでなければならないという事実を過小評価しないでください。知的にからかうことができれば、プログラマーはもっと喜んで本を読みます。

したがって、一般的な原則として、コメントで圧倒されることはありませんが、コメントを書く必要がある場合は、書き留めることができる最も明確なコメントであることを確認してください.

そして、個人的には、自己文書化コード (別名、スラッシュスターが 1 つ付いたコード) の大ファンではありません: 何ヶ月も書いた後 (私の個人的な尺度では数日です)、あなたの知性の一部を表すためにそのようなデザインを選択する本当の理由は、どうして他の人ができるのでしょうか?

コメントは、コード行の間の緑色のものだけではありません。それらは、あなたの脳がより喜んでコンパイルするコードの一部です。ブレインコードとしての資格があります (笑) コメントがあなたが書いているプログラムの一部ではないことを断言できませんでした。それらは、CPU に向けられていない部分にすぎません。

于 2009-02-13T16:08:36.567 に答える
0

研究によると、10 行のコードに対して約 1 行のコメントがあれば、最適な可読性が得られます。もちろん、配給量を 1/10 に保ち、それを超えたらパニックになる必要があると言っているわけではありません。しかし、どれだけコメントする必要があるかを知るには良い方法です。

また、コメントはコードの匂いであることも忘れないでください。つまり、それらは悪いコードを示している可能性がありますが、必ずしもそうであるとは限りません。その理由は、より理解しにくいコードほど多くのコメントが付けられるためです。

于 2009-02-13T21:53:54.303 に答える
0

何かを追加するときだけコメントしてください。

このようなものは役に立たず、読みやすさを確実に低下させます。

/// <summary>Handles the "event" event</summary>
/// <param name="sender">Event sender</param>
/// <param name="e">Event arguments</param>
protected void Event_Handler (object sender, EventArgs e)
{
}
于 2009-02-13T14:01:43.503 に答える
0

後でコードを確認する必要がある場合に理解できるように、十分にコメントするだけで十分だと思います。

全員にコメントすると、多くの時間が無駄になると思います。このルートに進むと、コードがさらに理解しにくくなる可能性があります。

読みやすいコードを書くことがおそらく最も重要な部分であることには同意しますが、コメントを省略しないでください。余分な時間をかけてください。

于 2009-02-13T13:39:20.483 に答える
0

読みやすいコードは最優先事項です。コメントは、Paul Tomblin が既に書いたように、Why の部分に焦点を当てるためのものです。

于 2009-02-13T13:40:39.777 に答える
0

コメントはなるべく控えるようにしています。コードは自明である必要があります。変数とメソッドに適切な名前を付けます。適切な名前を持つメソッドで大きなコード ブロックを分割します。1 つのこと、つまり名前を付けた目的を実行するメソッドを記述します。

コメントを書く必要がある場合。短くしてください。なぜこのコードブロックがこれを行うのかについて詳しく説明する必要がある場合、設計にすでに問題があると感じることがよくあります。

于 2009-02-13T13:46:16.847 に答える
0

通常、私は、記述しているコードの意図を明確に説明するドキュメント コメントのファンです。NDoc や Sandcastle などの気の利いたツールは、そのドキュメントを作成するための優れた一貫した方法を提供します。

しかし、私は何年にもわたっていくつかのことに気づきました。

  • ほとんどのドキュメンテーション コメントは、コードから実際に収集できないことは何も教えてくれません。もちろん、これは、最初からソース コードから表または裏を作成できることを前提としています。

  • コメントは、動作ではなく意図を文書化するために使用する必要があります。残念ながら、ほとんどの場合、これは使用方法ではありません。NDoc や Sandcastle などのツールは、コード自体から識別できるはずのことを読者に伝えるコメントを提供するように促す大量のタグを提供することによって、コメントの誤った使用を広めるだけです。

  • 時間が経つにつれて、コメントはコードと同期しなくなる傾向があります。これは、ドキュメンテーション ソフトウェアを使用しているかどうかに関係なく、ドキュメントを記述しているコードに近づけるため、ドキュメンテーションを容易にすることを目的としている傾向があります。ドキュメントはメソッド、プロパティ、イベント、クラス、またはその他の型のすぐ隣にありますが、開発者は、組み込みの動作が変更された場合にいつ更新するかを覚えておくのに苦労しています。その結果、ドキュメントはその価値を失います。

これらの問題は概して、コメントの誤用によるものであることに注意してください。コメントが意図を伝える手段としてのみ使用されている場合、特定のタイプまたはそのメンバーの意図が時間の経過とともに変化する可能性は低いため、これらの問題はそのままになります。(そうであれば、より良い計画は、新しいメンバーを作成し、新しいメンバーへの参照で古いメンバーを非推奨にすることです。)

コメントは、適切に使用すれば非常に価値があります。しかし、それは、それらが何に最もよく使用されるかを知り、その使用をその範囲に制限することを意味します. これを怠ると、コメントを削除するか、何らかの方法で修正する必要があるため、間違ったコメントや誤解を招くコメントが大量に発生し、多忙な作業の原因となります (コストが増加します)。

コメントが時間、エネルギー、お金の浪費にならないように、有意義な方法でコメントを使用するための戦略を持つことは価値があります。

于 2009-02-13T21:25:14.887 に答える