コメントはいかがですか？[閉まっている]

StackOverflow https://stackoverflow.com/questions/121945

  •  02-07-2019
  •  | 
  •  

質問

コメントのベストプラクティスは何ですか?いつ使用し、何を含めるべきですか?それともコメントも必要なのでしょうか？

役に立ちましたか？

解決

コメントは保守性を高めるために不可欠です。覚えておくべき最も重要なポイントは説明することです なぜ あなたは何かをしているのではなく、 何 あなたがやっている。

他のヒント

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

コメントはコードの背後にある「方法」ではなく「なぜ」を文書化するために使用されるべきだと思います...コード自体が「方法」を説明しています。なぜそれが行われるのか明確ではない操作がある場合は、そこにコメントを入れるとよいでしょう。

TODO と FIXME はコメントに入れられることもありますが、理想的にはソース コード管理ツールやバグ追跡ツールに入れるべきです。

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

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

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

  • 構造をより明確にするため（すなわち、どのループがここで終了したか)

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

  • コードが何をするのかを説明すると、

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

  • 回避策/バグ修正を示すため

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

  • 文書化目的のため

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

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

あなたは他の人のコードの何パーセントを読んですぐに理解できますか?おそらく私は古典的な ASP、Perl、C++ を読みすぎているのかもしれませんが、私が読んだもののほとんどは流し読みするのが難しいです。

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

いくつかのコメント:

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

コメントの問題は、コードと同様にメンテナンスする必要があるにもかかわらず、まったくメンテナンスされないことが多いことです。

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

// 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 );
}

コードがすべてを物語ります。コメントは必要ありません。

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

メソッド/関数/クラスには、すぐに明らかではなくても、何を行うのか、どのように実行するのか、何を取得し、何を返すのかについての短い説明が必要であり、通常 (私のコードでは) javadoc スタイルのコメント ブロックの形式で記述されます。 。

ブロック内コードでは、その動作を説明するために行ブロックの上にコメントを残すか、短くて不可解な関数呼び出しの場合は行末にコメントを残すことが多いです。

タグ検索を使用すると、SO にはコード コメントに関する議論がすでに山ほどあることがわかります。

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

コードのコメント化

見て コードの完成. 。このようなトピックには単純に最適です。

ライセンス： CC-BY-SA と 帰属
所属していません StackOverflow
scroll top