コード内のコメント-有用、無意味、有害？
どういうわけか、いくつかの古いモジュールのコードを調べて、コメントの役割について再度考えました。 本、ブログ、記事、フォーラムで何百万回も議論されてきた些細な質問ですが、それでもなお、生活に触れることがあります。 同時に、コメントの利点は危険よりもはるかに頻繁に書かれています。
したがって、私はいくつかの挑発的なステートメントを作成し、それらを例でバックアップしてみます。 何が起こるか見てみましょう。 これは、コード内の（Java）Docと通常のコメントの両方に適用されます。
だから：
1.解説は、有用、無意味、または有害である場合があります。
2.コメントに明確に明らかな利点がない場合、それはほとんどの場合有害です。
3.コメントは、見かけ以上に役に立たない/有害です。 コメントの欠如は、無駄なコメントよりも優れています。
4.コメントを書く前に、よく考えてみてください。 :)
（5.コメントはまだ必要ないと判断した後、3回見てください-コードは明確ですか？:)）
有用なコメントについては、すべてが明確です。 いつ：
-ビジネスロジックを含む80行のメソッドコードではなく、6行のコメントを読むだけ
-コメントには、実装されているあまり知られていないアルゴリズムまたはデータ構造へのリンクがあります（たとえば、「Aho-Korasikアルゴリズムを使用して部分文字列を検索する」、Wikipediaまたは特別なサイトへのリンク）
-コメントは、作成者が読み取りコードがここで見る可能性が最も高いアプローチを使用しない理由を説明します（たとえば、ORMフレームワークを使用する代わりに手書きのSQLクエリ、またはXMLでの検索にXPathではなくregexpが使用される理由）
-短い明確な使用例が解説に記載されています（特に、これが何らかの種類のカスタムAntタスクまたは類似のものである場合）。
これはほぼ間違いなく有用であり、時には必要なコメントです。
次に、他の一般的な例を見てみましょう。
このようなコメントは通常、オブジェクトフィールドのセッターゲッターを生成するときにデフォルトでIDEによって作成されます（次に、Javaにプロパティがあり、必要な合成メソッドがプログラマーに対して透過的にコンパイラによって生成された場合、この問題は発生しませんでした:)）。
解説は明らかに不要です。 コードには些細なことは何もありません。コメントは本質的にコードを複製します。 さらに、ここのコメントはコードエディターで3行かかります。 つまり コード自体とまったく同じです。 コード自体が、実際には合成コードであるだけでなく、Javaコードの規約により、読みやすくするために3行に拡張されているため、コメントもスペースを消費します。
Javaは、RubyやGroovyなどと比較して、すでに（コード行あたりの有用なアクションの平均数に関して）非印象的な言語であるため、不必要なコメントのために画面スペースを浪費する理由です。
もちろん、ここには微妙なポイントがあります。 このようなコメントを含むコードが汎用ライブラリのパブリックAPIの一部であり、それを使用するプログラマーがソースコードをほとんど見ず、Javadocを見る場合、これはまだ正常です。 しかし、このコードが私たちが開発したモジュールにあり、このクラスのソースがそのドキュメントよりも頻繁に見える場合（これはほとんど常に真実です）-これは私見です、「任意のAPI要素にコメントが必要」というルールが適用されます細心の注意を払って。
考慮された例は、多くの場合、 param 、 リターンタグがコメントにプッシュされるという事実によってさらに悪化します。これは多くの場合、有用な情報を伝えませんが、場所を食べます。 例：
/ **
*
*説明。
* param paramName1 paramName1
* param paramName2 paramName2
* param paramName3 paramName3
*ユーザーの名前を返します
* /
public String getUserName（String paramName1、int paramName2、int paramName2）{
/ *簡単な簡単なコード* /
}
（多くの場合、コードにはこのような意味のないコメントがありますが、コメントの本当に複雑な部分にはほとんどありません:)）
そして最後に、別の例。
//一時的なハック、なぜなら 今すぐうまくいく機能はサポートされていませんが、
//ただし、緊急に行う必要があります。 [シニア開発者名]のアドバイスで、彼はこのようにハッキングしました。
// 2004年4月21日、[開発者名]。
いくつかの例では、私は部分的に誇張していますが、一般的な考え方はこれから変わりません。
更新された：
コメントのリクエストに応じて、プログラマーがこのようなコメントを書かないように（そして他の多くの間違いをしないように）読むのに役立ついくつかの本へのリンクを提供します。
スティーブマッコネル。 完全なコード。 www.ozon.ru/context/detail/id/5508646
マーティン・ファウラー。 リファクタリング 既存のコードの改善。 www.ozon.ru/context/detail/id/4952415
したがって、私はいくつかの挑発的なステートメントを作成し、それらを例でバックアップしてみます。 何が起こるか見てみましょう。 これは、コード内の（Java）Docと通常のコメントの両方に適用されます。
だから：
1.解説は、有用、無意味、または有害である場合があります。
2.コメントに明確に明らかな利点がない場合、それはほとんどの場合有害です。
3.コメントは、見かけ以上に役に立たない/有害です。 コメントの欠如は、無駄なコメントよりも優れています。
4.コメントを書く前に、よく考えてみてください。 :)
有用なコメントについては、すべてが明確です。 いつ：
-ビジネスロジックを含む80行のメソッドコードではなく、6行のコメントを読むだけ
-コメントには、実装されているあまり知られていないアルゴリズムまたはデータ構造へのリンクがあります（たとえば、「Aho-Korasikアルゴリズムを使用して部分文字列を検索する」、Wikipediaまたは特別なサイトへのリンク）
-コメントは、作成者が読み取りコードがここで見る可能性が最も高いアプローチを使用しない理由を説明します（たとえば、ORMフレームワークを使用する代わりに手書きのSQLクエリ、またはXMLでの検索にXPathではなくregexpが使用される理由）
-短い明確な使用例が解説に記載されています（特に、これが何らかの種類のカスタムAntタスクまたは類似のものである場合）。
これはほぼ間違いなく有用であり、時には必要なコメントです。
次に、他の一般的な例を見てみましょう。
このようなコメントは通常、オブジェクトフィールドのセッターゲッターを生成するときにデフォルトでIDEによって作成されます（次に、Javaにプロパティがあり、必要な合成メソッドがプログラマーに対して透過的にコンパイラによって生成された場合、この問題は発生しませんでした:)）。
解説は明らかに不要です。 コードには些細なことは何もありません。コメントは本質的にコードを複製します。 さらに、ここのコメントはコードエディターで3行かかります。 つまり コード自体とまったく同じです。 コード自体が、実際には合成コードであるだけでなく、Javaコードの規約により、読みやすくするために3行に拡張されているため、コメントもスペースを消費します。
Javaは、RubyやGroovyなどと比較して、すでに（コード行あたりの有用なアクションの平均数に関して）非印象的な言語であるため、不必要なコメントのために画面スペースを浪費する理由です。
もちろん、ここには微妙なポイントがあります。 このようなコメントを含むコードが汎用ライブラリのパブリックAPIの一部であり、それを使用するプログラマーがソースコードをほとんど見ず、Javadocを見る場合、これはまだ正常です。 しかし、このコードが私たちが開発したモジュールにあり、このクラスのソースがそのドキュメントよりも頻繁に見える場合（これはほとんど常に真実です）-これは私見です、「任意のAPI要素にコメントが必要」というルールが適用されます細心の注意を払って。
考慮された例は、多くの場合、 param 、 リターンタグがコメントにプッシュされるという事実によってさらに悪化します。これは多くの場合、有用な情報を伝えませんが、場所を食べます。 例：
/ **
*
*説明。
* param paramName1 paramName1
* param paramName2 paramName2
* param paramName3 paramName3
*ユーザーの名前を返します
* /
public String getUserName（String paramName1、int paramName2、int paramName2）{
/ *簡単な簡単なコード* /
}
（多くの場合、コードにはこのような意味のないコメントがありますが、コメントの本当に複雑な部分にはほとんどありません:)）
そして最後に、別の例。
//一時的なハック、なぜなら 今すぐうまくいく機能はサポートされていませんが、
//ただし、緊急に行う必要があります。 [シニア開発者名]のアドバイスで、彼はこのようにハッキングしました。
// 2004年4月21日、[開発者名]。
いくつかの例では、私は部分的に誇張していますが、一般的な考え方はこれから変わりません。
更新された：
コメントのリクエストに応じて、プログラマーがこのようなコメントを書かないように（そして他の多くの間違いをしないように）読むのに役立ついくつかの本へのリンクを提供します。
スティーブマッコネル。 完全なコード。 www.ozon.ru/context/detail/id/5508646
マーティン・ファウラー。 リファクタリング 既存のコードの改善。 www.ozon.ru/context/detail/id/4952415
All Articles