comments - あなたのコメントはどうですか？

Question

コメントのベストプラクティスは何ですか? いつ使用する必要があり、何を含める必要がありますか? それともコメントが必要ですか？

score 62 · Accepted Answer

保守性にはコメントが不可欠です。覚えておくべき最も重要な点は、何をしているのかではなく、なぜそれをしているのかを説明することです。

score 10 · Accepted Answer

学校では、すべてにコメントを付けるというルールがあり、コメントがコードよりも重要でした。ばかげていると思います。

コメントは、「方法」ではなく、コードの背後にある「理由」を文書化するために使用する必要があると思います...コード自体が「方法」を説明しています。なぜそれが行われたのかが明確でない操作がある場合は、コメントするのに適した場所です。

TODO と FIXME はコメントに記載されることもありますが、理想的には、ソースコード管理ツールとバグ追跡ツールに記載する必要があります。

役に立たないように見えるコメントを気にしない唯一の例外は、ドキュメントジェネレーターです。これは、コメントされている関数のドキュメントのみを出力します。その場合、すべてのパブリッククラスと API インターフェイスは、少なくともドキュメントを取得するのに十分なコメントを付ける必要があります。生成されます。

score 8 · Accepted Answer

多くの場合、答えは次のとおりです。コメントが良いか悪いかは、コメントを書いた理由が決定に非常に重要だと思います。コメントには複数の理由が考えられます。

構造を明確にする (つまり、どのループがここで終了したか)

悪い:これはコードの匂いの可能性があるようです。コードが非常に複雑で、それを解決するためにコメントが必要なのはなぜですか?

説明するために、コードが何をするか

非常に悪い:これは私の意見では危険です。後でコードを変更してコメントを忘れてしまうことがよくあります。今のコメントは間違っています。これは非常に悪いです。

回避策/バグ修正を示す

良い:問題の解決策が明確に見えることもありますが、単純なアプローチには問題があります。問題を修正する場合は、このアプローチが選択された理由についてコメントを追加すると役立つ場合があります。そうしないと、後で別のプログラマーが、コードを「最適化」してバグを再導入すると考える可能性があります。Debian OpenSSL の問題について考えてみてください。Debian 開発者は、初期化された変数を削除しました。通常、初期化された変数は問題ですが、この場合はランダム性のために必要でした。コードのコメントは、それを解決するのに役立ちました。

文書化目的

良い:一部のドキュメントは、特別な形式のコメント (Javadoc など) から生成できます。公開 API を文書化することは役に立ちます。これは必須です。重要なのは、ドキュメントには実装ではなくコードの意図が含まれていることを覚えておくことです。それで、「なぜメソッドが必要なのか（そしてどのように使用するのですか）」または「メソッドは何をしますか？」という質問のコメントに答えます。

score 7 · Accepted Answer

理想的には、プログラムはコメントではなくコードでリーダーと通信できます。私の意見では、他のプログラマーがすぐに理解できるソフトウェアを作成する能力は、最高のプログラマーと平均的なプログラマーを区別します。通常、あなたやあなたの同僚がコメントなしでコードのセクションを理解できない場合、これは「コードのにおい」であり、リファクタリングを行う必要があります。ただし、平均的な開発者をガイドするいくつかのコメントが必ずしも悪いとは限らない、いくつかの古風なライブラリやその他の統合があります。

score 2 · Accepted Answer

コメントを削除する新しい動きは悪いと思います...理由は、コメントを必要としないわかりやすいコードを書いていると考えるプログラマーが多いからです。しかし、実際にはそうではありません。

他の人のコードの何パーセントを読んですぐに理解できますか..多分私は古典的なASP、Perl、C++を読みすぎていますが、読んだほとんどのものはスキミングするのが難しいです.

誰かのコードを読んで、完全に混乱したことはありませんか。彼らが書いている間、これはがらくただと思ったと思いますが、私はあまり気にしません。彼らはおそらく、ああ...これは非常に巧妙で、超高速になると思ったでしょう。

score 2 · Accepted Answer

いくつかのコメント：

コメントは、コードから簡単に推測できないすべてのもの (複雑な数学的アルゴリズムなど) にとって重要です。

コメントの問題は、コードのように維持する必要があるのに、まったく維持されていないことが多いということです。

次のようなコメントは好きではありません。

// Create the "Analyze" button
Button analyzeButton = new Button();
analyzeButton.Text = "Analyze";
analyzeButton.Location = new Point( 100, 100 );
Controls.Add( analyzeButton );

より良い：

CreateAnalyzeButton();


void CreateAnalyzeButton()
{
    Button analyzeButton = new Button();
    analyzeButton.Text = "Analyze";
    analyzeButton.Location = new Point( 100, 100 );
    Controls.Add( analyzeButton );
}

コードがすべてを物語っています。コメントは不要です。

score 1 · Accepted Answer

シナリオによると思います。

メソッド/関数/クラスには、何をするか、どのように行うか、何を取り、何を返すかについての簡単な説明が必要です。 .

ブロック内コードでは、行のブロックの上にコメントを残して、それが何をするかを説明するか、短く不可解な関数呼び出しの場合は行の最後にコメントを残す傾向があります。

score 0 · Accepted Answer

0

Code Completeをご覧ください。そのようなトピックに最適です。

于 2009-11-02T05:16:25.437 に答える

score 0 · Accepted Answer

タグ検索を使用すると、SO がコードコメントについてすでに多くの議論を行っていることがわかります。

https://stackoverflow.com/questions/tagged/comments

コメントコード

comments - あなたのコメントはどうですか？

9 に答える 9

Related

Reference