0

まず、この質問では、ソース コードのコメントが良いか悪いかという論争から離れたいと思います。なぜ、何を、どのように伝えるコメントについて話しているときに、人々が何を意味するのかをより明確に理解しようとしているだけです。

「コメントは理由を教えてくれ、コード自体が方法を教えてくれるはずだ」というようなガイドラインをよく目にします。抽象的なレベルでのステートメントに同意するのは簡単です。しかし、人々は通常、これをドグマのように落とし、それ以上の説明なしに部屋を出ます。これが非常に多くの異なる場所や文脈で使用されているのを見てきました。人々はキャッチフレーズに同意できるように見えますが、まったく異なることについて話しているようです.

では、質問に戻ります: コメントが理由を教えてくれるとしたら、私たちが話している理由は何ですか? これが、そもそもそのコードが存在する理由ですか? これは、そのピースコードがすべきことですか? 誰かが明確な説明をしてから、いくつかの良い例を追加していただければ幸いです (悪い例は実際には必要ありませんが、対比のために自由に追加してください)。

この質問を重複または論争としてすぐに閉じないでください。私はそれを非常に客観的にするために一生懸命努力しました。コメントが良いか悪いかについては多くの質問がありますが、理由を示すコメントの良い例は何かという具体的な質問に答えている人は誰もいません。

ありがとう、

4

1 に答える 1

1

コメントは主に次の 2 つの目的を果たします。

  • 要約すると。多くの人は「コードを読めるのに、なぜこのメソッドを文書化するのですか?」と言うでしょうが、メソッドの目的/機能を説明する 1 行のテキストは、30 行のテキストよりもはるかに読みやすく、理解しやすいことがよくあります。コード、特にそのコードが他のメソッドを呼び出す場合は、同様に読む必要があります...

  • コードからは明らかでないこと、つまり理由、または方法の詳細を説明します。簡単な例としては、「.net の ReplaceChild メソッドが機能しないため、新しい XmlElement を追加してから古いものを削除する必要があります!」、「反復的なニュートン ラフソン法を使用して X を解く」、または「してはならない」などがあります。読み取りスレッドがまだ実行されている可能性があるため、ここでポートを閉じてください」、または「パフォーマンスが重要な場合はこの方法を使用しますが、この方法では最大 5% のエラーが発生する可能性があることに注意してください」

于 2014-11-23T17:25:28.887 に答える