メソッド内にコメントを書くことは良い習慣ではありませんか？
友人から、メソッド内にコメントを書くのは良くないと言われました。彼は、メソッド定義（javadocs）だけにコメントを入れるべきであり、メソッド本体の内部にはコメントを入れるべきではないと述べました。彼が本の中で読んだように、コード内にコメントがあることはコードに問題があることを意味します。彼の推論はよくわかりません。メソッド本体内にコメントを書くことは良いことだと思います。他の開発者がそれをよりよく、より速く理解するのに役立ちます。コメントを入力してください。
あなたの友人は間違っており、ほとんどのプログラマーは彼に同意しません。コメントは、いつでもどこでも、理解を助けるのに最も役立つと思う場所に書いてください。
友達を無視して。必要に応じてコメントしてください。しかし、コードが自明になるように努力して、コメントではないが必要になるようにしてください。お使いのコンピュータはコメントを実行していないので、コメントが実際に起こっていることと同期しなくなるのは簡単です。
私はコメントのブロックを使用して、特に注意が必要なロジックを説明する傾向があります。そして、ロジックをより明確にし、説明の必要性をなくすようにします。
良いコードは自己文書化です。メソッドは正確に1つのことを行う必要があり、その1つはメソッド名とコメントの仕様から明らかです。したがって、ロジックを説明するメソッドにコメントが必要な場合は、メソッドを単一責任メソッドに分割する必要があることを示唆しています。
今、現実のために。あなたは複雑なスパゲッティコードのコードベースに直面していて、メンテナに素敵になりたいと思っています。 800万行のコードをリファクタリングする時間や義務がありません。そうしたとしても、すべてが複雑であるため、ニュアンスが生じます。職業はなんですか？
この意見に多くの人が反対していることに驚いています。
- 適切なコードは自己文書化する必要があるため、メソッド名、変数名などを慎重に選択する必要があります
- メソッドは、メソッド全体とコメントを1つの画面に表示できないほど長くすべきではありません。
とはいえ、例外はあります。しかし、それらは例外です。例外は例外です。数が少ないということです。コードをインラインで説明する必要があるのは、直感に反することがある場合だけです。
メソッドでコメントが必要になる一般的な状況は、ローカルハックを適用して速度を最適化する場合ですが、最初の読み取りで別のプログラマーにwtfの瞬間を与える可能性があります。それはコメントを追加するのに良いポイントです。
ただし、一般的には、いいえ。メソッドにコメントを追加しないでください。
私は彼がこのようなケースについて話していると思います：
public void upload() {
// destination Host
String Host = ....
}
コメントではなく、より明示的な変数名を指定することで、コードを改善できる場合：
public void upload() {
String destinationHost = ....
}
あなたの友人はロバート・C・マーティンの「クリーンコード」を参照していると思います。しかし、彼は状況を少し単純化しすぎていると思います。この本は、メソッドに明確でわかりやすい名前を付けることについて述べています。これは誰もが知っている必要がありますが、十分に繰り返すことはできません。また、明確でわかりやすい名前を付けることができるコードブロックを独自のメソッドにラップすることにより、メソッドを非常に小さくすることをお勧めします。したがって、コードのブロックにその機能を説明するコメントが必要だと思われる場合は、適切な名前を付けた別のメソッドにする必要があります。理論的には、すべてのメソッドが5行未満であり、すべてにわかりやすい名前が付いている場合は、コメントで説明しなくても、何をするのかは明らかです。
ただし、メソッド内にコメントを含めてはならないという意味ではありません。重要なのは、コメントが冗長であってはならないということです。情報を追加する必要があります。たった1つのことを行うメソッドがあり、そのことからその名前が明らかである場合、その方法を説明するコメントは必要ありません。ただし、なぜ特定の方法で機能するのかを説明するコメントを付けることは、完全に理にかなっています。あるアルゴリズムを別のアルゴリズムよりも選択した理由、またはあるデータ構造を別のアルゴリズムよりも選択した理由を説明するコメントが必要な場合があります。つまり、コード自体にコードの動作を説明し、コメントに設計上の決定の理由を説明する必要があります。 e。なぜ物事がこの特定の方法で行われるのか。
本はコメントするのではなく、悪いコードをリファクタリングすることを勧めます。これは確かに理論的には素晴らしいアイデアですが、実際には、それを行うための適切な単体テストのセットを備えた実用的な単体テストフレームワークなど、時間やインフラストラクチャがない場合があります。厄介なコードベースに直面している場合があります。昨日作業する必要があり、前に進む唯一の方法は、厄介な部分を理解し、コメントして自分のメモを作成することです。
はい、あなたは間違いなくJavaのメソッドの中にコメントを書きます。
Sunのコード規則 は次のように言います：
Javaプログラムには、実装コメントとドキュメントコメントの2種類のコメントを含めることができます。実装コメントはC++にあるコメントで、
/*...*/と//で区切られています。ドキュメントコメント（「docコメント」として知られています）はJavaのみであり、/**...*/で区切られます。ドキュメントのコメントは、javadocツールを使用してHTMLファイルに抽出できます。
したがって、メソッド内のコメントは実装コメントです。
私はあなたの友人に強く反対し、インライン関数コメントは良いコードを書くのに非常に重要な部分であると主張します。関数のコメントは、コードのクライアントがコードが何をすることになっているのか-パラメータと戻り値が何を意味するのか、入り口と出口で期待される不変の種類などをよりよく理解できるように設計されています。ただし、インラインコメント、ただし主にコードのメンテナーに向けられており、理想的にはコードの原作者のための一連のメンタルノートとして書かれています。彼らは、他の人が読んだ複雑な方法を見て、元の作者が考えていたものを直感することを可能にします。また、コメントがコードの意図やコードの想定を説明している場合、誤動作が検出されたときにコードの一部がどのように誤っているかを理解するのがはるかに簡単になるため、バグの診断が容易になります。
個人的には、インラインコメントが役立つと思います。なぜなら、これから書こうとしているコードが正しく機能することを自分で証明する必要があるからです。多くの場合、私は最初に意図が何であり、それがどのように機能するかを明確にコメントしない限り、コードを書かない習慣をつけます。私の説明が正しくないか、Edgeのケースが考慮されていないため、コードの愚かな間違いを防ぐことができます。
もちろん、誰もが独自のコーディング規律を持っており、インラインコメントなしでコードを記述し、代わりにコードを複数の小さなメソッドに分割する方が簡単な人もいるでしょう。ただし、経験から、インラインコメントは開発およびデバッグ中に非常に貴重であり、別のプロジェクトに移った後もずっとコードを調べて維持する必要がある他の人にとって非常に役立つことがわかりました。
あなたの友達は、コメント自体が「コードのにおい」ではないとしても「 デオドラント 」であるという考えを表現している可能性があります。これはメソッド内コメントに固有のものではありませんが、プリアンブルコメントよりもメソッド内コメントの方がより真実になる傾向があります。
コメントを書くとき、それは通常何かを説明することです。説明が必要な場合-まあ、それは自明ではありません。素晴らしいコードは自明です。つまり、コメントを追加すると、説明がなくても、説明の失敗をカバーできます。したがって、そのようなコメントを書くたびに、コードを変更する代わりに-名前の変更、メソッドの抽出などによって-にmake自明ですが、理想に達していません。
しかし、私たちは皆、何度も完璧に達していません。また、わかりにくいコードを文書化せずに残すよりも、説明コメントを追加する方がよい場合がよくあります。
良いコメントは、なぜではなく、なぜであるかを説明しています。これがここでの主な違いです。ほとんどの人はあなたがやっていることをフォローすることができますが、なぜそれをしたのかは追加のコメントが必要です。これらのコメントは、可能な限り操作に近い必要があります。
あなたのコード（または誰かの本当にひどく文書化されたコード）にコメントするとき、あなたはしばしば透け感嫌悪感、嫌いに直面するかもしれませんまたはwrath。コードはイライラする予期しない方法で動作する可能性があり、いくつかの締め切りに間に合わせるために非常に邪悪なハックを追加する必要がある場合があります。
これらのすべての場合において、コードのそれぞれの部分に重い罵り言葉（ linux kernel fuckcount を参照）で注釈を付けることによって感情を表現することは一般的な方法です。これらのコメントはメソッド内に存在する必要があるため、自動ドキュメント化されたAPIに表示されないため、上司もクライアントも、ソースコードにとらわれない人にも表示されません。
しかし、ソースを研究するとき、あなたの仲間のプログラマーは安心と幸福を感じます。 （そしてもちろん、あなたは自分自身にメモを追加したり、ある程度のコミュニケーション手段としてソースコードを使用したりできます。#TODO: add more examples here）
もちろん、これらの種類のコメントはそもそも存在しないはずである、または最終リリースの前に削除する必要があると主張するかもしれませんが、最近のソフトウェアプロジェクトのリリースサイクルは非常に短く、一部のコメントは依然として関連しています多くの場合、毎晩ビルドするので、おそらくあなたの友人はread（そして書き込み）の間に行を学ぶことを始めるべきです。
コメントを必要としないコードがあるのは素晴らしいことです。物事を取得、保存、削除すると、何が起こっているのかよくわかり、コメントは不要です。
コードが乱雑になり、リファクタリングの候補となる場合があるため、その間にコメントする必要がある場合があります。
今日、私はコード行が予期したことをしないようにしました。どうやら.netデータテーブルは、インポートされた行が新しいレコードであるとは考えていません。テーブルからレコードを挿入しても何も起こりません。インポートされる行は、最初にステータスを変更する必要があります。必要なのは簡単なコメントだけなので、6か月後に戻って「何が必要なのか」と考えると、わかります。
他のプログラマーがコードで何をしているのかわからないと思うときはいつでも、プログラマーがメソッド内にコメントを入れるのが一般的です。また、プログラマーはメソッド内にTODOコメントを入れることがあります。ただし、メソッド内にコメントが多すぎる場合は、一歩下がって複雑すぎることをしているのではないかと考える必要があるかもしれません。つまり、他のプログラマがコードを読むのは難しいため、他のプログラマにとって明らかなことについてはコメントしないようにする必要があります。
友だちの提案を積極的に取り入れるために、変数とメソッドに適切な名前を付け、各メソッドを小さくし、スタッフが多すぎないようにすることで、コメントしすぎないようにすることができます。
彼が言った理由は、関数はそれぞれが単一の概念的な操作だけをカプセル化するのに十分に短くあるべきだと彼が信じているからだと思います。
私は必ずしもその信念に極端に同意しているわけではありませんが（そのようなコードを読むことは悪夢になる可能性があることを含むさまざまな理由により）、もしそうした場合、関数ごとにコメントが1つしかないということになるかもしれません。関数ごとに1つの概念と概念ごとに1つのコメント。
どちらの方法でも、選択や動作がすぐに分からないコードがあるときはいつでもコメントを使用します。多くの場合、パフォーマンスの考慮事項や難解な数学に関係しています。そのようなことは関数のコンシューマーに直接関係しないことが多いので、ドキュメントから非表示にすることは実際には良い考えだと私は主張します。
あなたの友人はjavadocについて話していたと思います。javadocは、次のように、メソッド宣言の上にある（そして余分なアスタリスクで装飾されている）場合にコメントからドキュメントを生成します。
/**
get a webpage for a given url
@param url: the url to get
@returns String: the http-source
*/
public String getWebpage (String url) {
...
このコメントをメソッド内に置くと、役に立たなくなります。
したがって、-経験則として：Javaソースのメソッドの上にコメントを入れます。
例外が発生する可能性があります。私は同意します：短いメソッドを使用し、自己文書化コードを記述します。ただし、ツールとしてのjavadocはコメントの複製を奨励します。 :)
ゼロから作成されたメソッドでは、ヘッダー内にのみその機能を文書化できるという点を認めます。しかしながら。
バグが発見され、微妙なニュアンスを見落とした場所にコメントが挿入されることがよくありますメソッドに単一の責任しかない場合でも-正直に言うと、レガシーコードではほとんどありません。さらに、簡潔なコメント付きの短い変数名をより簡単に消化して後で再利用できる場合、変数名が40文字（2か所でのみ使用される場合でも）になる理由はありません。簡潔で簡潔な方法が最適ですが、何よりも、メール、手紙、詩だけでなく、他のプログラマとのコミュニケーション手段にもなります。そしてそれに私は引用を追加します：
「この手紙を短くする時間がないので、この手紙を長くしただけです。」
ブレーズ・パスカル（1623-1662）Lettres provinciales
コメントはコードをよりプログラマーフレンドリーにするだけで、コメントは実行されないことに注意してください。
数か月後にコードを読んだ場合、コメントによってコードが読みやすくなります。
コードを保守しやすくし、コードを見る他のプログラマーは、実装したロジックを理解しやすくなります。
コードが数行しかないメソッドでも、常にコメントを追加する必要があるという意味ではありません。
たとえば、次のコードは自明であり、その機能を明確にするためにコメントを必要としません
public String getName(){
return name;
}
メソッドが大きい場合は、コメントを追加して、プログラマーがそれを見たときにいつでも読みやすくします。
コーディング中にコードは自明だと思うかもしれませんが、6か月後にコードを見ると、6か月前に追加したコメントが間違いなくあなたや他のプログラマーがコードをすばやく理解するのに役立ちます。
インラインコメントの問題は、コードとともに維持する必要があることです（関数/メソッド/モジュール/クラスレベルのコメントにも当てはまりますが、それほどではありません）。神は、コメントがドキュメント化されたコードとまったく関係のないソースコードがどれだけ残っているかを知っています。IMOは、コメントがまったくないのと同じかそれよりも悪いです。
理想的には、インラインドキュメントは次の状況に限定する必要があります。
whyの正当化とともに、大幅に最適化または「トリッキー」なコードを説明します。コードは非常に最適化または「トリッキー」です（「パフォーマンス要件Xが欠けていたため、プロファイリングでボトルネックが発生していることがわかりました。セクション;以下の最適化によりY％のパフォーマンスが向上しました "）;
標準または要件を参照（「DTED 0ポスト間隔は30アーク秒」）。
さらなる分析/開発が必要なコードを特定する（「TODO」）。
コード文書化の第一法則-明白なものを文書化しないでください。コード文書の第一法則の当然の結果-可能な限り明白なコードを記述します。
まず、あなたの質問は特にJava指向でした-これは答えに大きな影響を与えます。
必須であるコメントの量は、作業している言語に大きく関連しています。
JavaおよびC＃などの一部の言語は、自己文書化コードの概念に非常に適しています。これらの言語では、コード自体を可能な限り読みやすく説明的なものにするために、最善の努力を尽くしています。次に、言語内でネイティブに記述できないものに対してのみインラインコメントを追加します。
SQLなどの一部の言語は、読みやすくすることがより困難です。構文、評価の順序、ネストなどにより、自己文書化された方法で設計することはより困難になります。同じ基本的なアプローチが引き続き適用されます。できるだけ言語を使用することに焦点を当て、次にコメントを追加して、不明確または混乱している領域を補います。
全体的にコメントを100％廃止することはできませんが、コードをより自己記述的にすることにより、コメントのneedをできるだけ削除することが目標です。これらの取り組みの結果、通常は全体的なコードが減り、コードが整理されます。コメントがまだ存在するかどうかに関係なく、これはコードの保守性とアプローチ性が大幅に向上することを意味します。これは、実際にコメントが意図するものです。
Javadoc（またはDelphiのオートコンプリートヒントでも）が、（javadocの機能を追加する以外に）人のコーディング方法を変更する必要があるという考えは、かなりばかげています。
最初に来た友達にjavacとjavadocのどちらで質問しますか？
牛かオレアリー夫人のどちらが最初に来たかを尋ねるようなものです
また、javadocはクラスと関数を実装する人向けである必要があり、コード内のコメントはコードを保守している人向けです。特にプライベートメソッドを使用する場合、コードの内容を確認するためにコードを確認する必要はありません。それがドキュメントの目的です。しかし、1つのエラーによる毛むくじゃらのために誰かが何かを微調整する必要がある場合は、メソッドでそれをコメントアップする必要があります。
彼は明らかに、実際にはバグ修正であるコードの90％がすべて悪いと想定しています。私は「実用的なプログラマー」を読んだことがありませんが、彼がその本を参照していないと思います。
パーティーがかなり終わったので、私は2セントを投げます。ビジネスロジックの特定のビットを説明するとき、または予期しないEdgeケースをカバーするために何かを追加する必要があるときは、コメントを使用します。
コードは時間の経過とともに進化し、事前に知られていないことを考慮します。そのため、バンドエイドを適用すると、それが既知であると想定する代わりに、なぜバンドエイドをオンにすると、時々役立ちます「ああ、ところで、私はこれを修正する必要があり、ここにバグトラッカー参照があります。周囲の会話をたどることができます」というコード内に小さなブロックを追加するには、私の場合（FogBugzを使用しているため）は次のようになります。 ：
_//Case: 1234 ~ Throttling based on unusual activity per ABC request.
Throttler myThrottler = new Throttler( oldActivity );
_または何でも。だから私のポイントは、場違いに見えて読めないものはおそらくインラインドキュメントに適した場所だということです。集めた知識は美しいものです。
しかし、私の最初のポイントは私のビジネスロジックでした。文字通り、ストアドプロシージャにブロックがあり、このAMを書き直そうとしています。これには、いくつかのビジネスルールが前にあります。
_/****************************************************************
author yourstruly
date 2010-11-18
descrip intended use is to blah blah blah
ended up over actual measured blah blah blah according to blah blah blah
rules from the customer are:
If the sum of the blah blah blah is higher than the blah blah blah
and the blah blah blah contain blah blah blah,
and the blah blah blah is non-zero,
recalculate the blah blah blah to fit within the blah blah blah
Additional rules for us internally:
if the blah blah blah originally read blah blah blah don't blah blah blah (set to zero)
rewritten here with (1) traceable statements for the where clauses.
If
the blah blah blah(1) is higher than the blah blah blah (2)
and the blah blah blah (3)
and the blah blah blah is non-zero (9)
and the blah blah blah is lower than the blah blah blah (4)
and the edited blah blah blah is higher than the blah blah blah (5)
then recalculate the blah blah blah (6)
// See note lower in this document on the math
If
the blah blah blah(1) is higher than the blah blah blah (2)
and the blah blah blah (3)
and the blah blah blah is higher than the blah blah blah (7)
then set the blah blah blah to zero (8)
(7) dictates the same as (4) but it's easier to do (7)
****************************************************************/
Sorry for the blah blah blah's but proprietary rules and all that ;)
_そして、突然、コードに要件（！）がコメントとして埋め込まれ、コメントを/*(1)*/（私はそうする）として参照できるようになるので、次の従業員が簡単に追跡できるようになります。 （それはそうでした、そして彼はすぐに微調整が必要な部分を見つけることができました）そして、誰かが仕様が何であるか知りたいのであれば、彼らは上から解説を読むことができ、誰かが疑似コードが何であるのか知りたいのであればそこで、誰かが疑似コードをコードに変換したい場合は、そこに行きます。私にとってこれは（メールの場合は）元のリクエストを保持し、あまり考えずに一連の思考をすばやく集めることができるので（私の場合は）ずっと読みやすく、簡単な変換を使用できます。実際のコードに擬似。
そしてはい、インラインコメントがあり、要件がデータと完全に一致していないためデータを微調整する必要があったため、疑似コードでは期待どおりに機能しなかったと述べています。しかし、それが私のポイントです。 Edgeケースをインラインで文書化し、ロジックに従うためにコード内に疑似コードを残したので、元の要件から何が期待されているかをすべて知っていました