コメントがコードの実行内容を説明している場合のみ。
メソッドまたはブロックで何が起こっているのかを知りたい場合は、コードを読みます。とにかく、特定のプロジェクトに取り組んでいる開発者は、少なくとも記述された内容を読んでそれが何をしているかを理解するのに十分なほど開発言語に精通していることを願っています。
極端な最適化のいくつかのケースでは、誰かがあなたのコードがしていることを理解するのを困難にするテクニックを使用しているかもしれません。このような場合、コメントを使用して、そのような最適化の理由だけでなく、コードの実行内容を説明する必要があります。大体の目安は、実装言語とプロジェクトに精通している他の誰か（または複数の他の人々）にコードを見てもらうことです。理由と方法の両方を理解できない場合は、理由とコメントの両方にコメントする必要があります。その方法。
ただし、コードで明確でないのは、なぜあなたが何かをしたのかということです。他の人には明らかでない可能性のあるアプローチをとる場合は、自分がした決定をした理由を説明するコメントが必要です。コードレビューのように、なぜYではなくXをしたのかを知りたくなるまで、コメントが必要であることに気付かないかもしれません。それを見る人全員がコードに回答を取り込むことができます。将来は。
ただし、最も重要なことは、コードを変更するときにコメントを変更することです。アルゴリズムを変更する場合は、必ずアルゴリズムXをYに置き換えた理由でコメントを更新してください。古くなったコメントは、コードの匂いがさらに大きくなります。
これは今のところ特に耳障りです。今週末、リサーチアルゴリズム（実際には公開されていないもの）を実装する、非常によく名前が付けられた、非常にクリーンでコメント化されていないコードを調べました。私はそれに慣れています。私の隣に座っているのは発明者で、コードは数年前に誰かによって書かれました。 かろうじてフォローすることができます。
あなたの同僚は十分に経験がありません。
コメントは、理由ではなく、理由を説明する必要があります。
Howタイプのコメントは、通常、リファクタリングを使用してより適切に処理されます。個人的には、通常、リファクタリングを支持するコメントは避けます。
前：
# convert to cents
a = x * 100
# avg cents per customer
avg = a / n
# add to list
avgs < avg
t += 1
後：
total_cents = total * 100
average_per_customer = total_cents / customer_count
track_average(average_per_customer)
あなたの同僚を異端者と宣言します！私の異端者のブーツはどこにありますか？
強迫的なコメントは悪く、メンテナンスの頭痛の種であり、コメントは、名前の付いたメソッド、クラス、変数などの代わりにはなりません。 なぜ 何かがそれが6か月でコードを維持しなければならない貧しいばか者にとって非常に貴重であることができる方法です-特にその貧しいばか者があなたであるようになってしまうとき。
私が取り組んでいるコードからの実際のコメント：
// If this happens, somebody's been screwing around with the database definitions and
// has removed the restriction that a given alarm may have only one entry in the
// notifications table. Bad maintenance programmer! Bad! No biscuit!
// If an alert is active on our side but inactive on theirs, that might mean
// they closed the alert. (Or that we just haven't told them about it yet.) The
// logic comes later; for now, we'll just compile it in a list.
// If we know for a fact that an alarm isn't getting through, we're going to whine pretty
// aggressively about it until it gets fixed.
理想的には、コードは十分にコード化されているため、自動的に説明的である必要があります。現実の世界では、非常に高品質のコードがコメントを必要とすることもあります。
絶対に避けなければならないのは、「コメントコードの冗長性」（コードに何も追加しないコメント）です。
i++; // Increment i by 1
次に、優れた（そして維持/調整された）コード設計とドキュメントがある場合、コメントはさらに役に立ちません。
ただし、状況によっては、コメントがコードを読みやすくするのに役立ちます。
while( foo )
{
if( dummy )
{
}
else // !dummy
{
}
} // end while( foo )
コメントも維持し、同期させる必要があることを忘れないでください...古くなった、または間違ったコメントはひどい痛みになる可能性があります！また、原則として、コメントしすぎると、プログラミングがうまくいかない場合があります。
メソッドまたはプロセスを「コードのにおい」として分類的に定義することは、「熱狂的なにおい」です。用語は新しい「有害と見なされる」になりつつあります。
これらのことはすべてガイドラインであることに注意してください。
他の回答の多くは、コメントがいつ正当化されるかに関して良いアドバイスを提供します。
個人的にはコメントをほとんど使わない。自明ではないプロセスの目的を説明し、数週間のチューニングを必要とするものを自分で変更することを検討している可能性がある人には、時折死の脅威を残してください。
幼稚園児が理解できるようになるまですべてをリファクタリングすることは、時間を効率的に使用できない可能性が高く、おそらくより簡潔なバージョンよりもパフォーマンスが低下します。
コメントは実行時間に影響しないため、考慮すべき唯一の問題はメンテナンスです。
ここでの主な問題は、「コードのにおい」という用語の意味です。
多くの人（あなたも含めて）は、コードのにおいがエラーに近いもの、または少なくとも修正が必要なものであることを理解しています。多分あなたはそれを「アンチパターン」の同義語と考えます。
これは用語の意味ではありません！
コードの匂いのメタファーは Wards Wiki に由来し、強調しています：
CodeSmellは、何かが間違っている可能性があるというヒントであり、確実ではないことに注意してください。完全に適切なイディオムは、誤用されることが多いため、またはほとんどの場合に機能するより簡単な代替手段があるため、CodeSmellと見なすことができます。 CodeSmellを呼び出すことは攻撃ではありません。これは単に、よく見る必要があるという兆候です。
つまり、コメントがコードの匂いであるということはどういう意味ですか。つまり、コメントが表示されたら、一時停止して考える必要があるということです。おそらく、変数の名前を変更したり、「抽出メソッド」のリファクタリングを実行したりできます。あるいは、コメントが実際に最良の解決策である場合もあります。
つまり、コメントがコードのにおいであるということです
編集：私はこれらの2つの記事をどんどん詰め込みました、それは私よりそれを説明しています：
場合によっては、適切なネーミング、リファクタリングなどでコメントを置き換えることはできません。次の実際の例を見てください（言語はGroovy）。
response.contentType="text/html"
render '{"success":true}'
奇妙に見えませんか？おそらくコピーペーストエラー？バグ修正の叫び？
今コメントと同じ：
// DO NOT TOUCH THE FOLLOWING TWO LINES; the ExtJS UploadForm requires it exactly like that!!!
response.contentType="text/html" // must be text/html so the browser renders the response within the invisible iframe, where ExtJS can access it
render '{"success":true}' // ExtJS expects that, otherwise it will call the failure handler instead of the succss handler
ルールは非常に単純だと思います。完全に見知らぬ人があなたのコードを見るのを想像してください。おそらく、5年後には自分のコードを知らない人になるでしょう。この見知らぬ人のためにあなたのコードを理解するための精神的な努力を最小限に抑えるようにしてください。
適切なコメントを付けるための良いアイデアは、コメントを書くことから始めることです。
// This function will do something with the parameters,
// the parameters should be good according to some rules.
myFunction(parameters)
{
// It will do some things to get started.
// It will do more with the stuff.
// It will end doing things with the stuff.
}
これにより、メソッドを簡単に抽出してコメントを取り除くこともできます。
コードにこれらのことを伝えさせるだけ！これが非常に良い方法でどのように書き換えられたか（カット/ペースト）をご覧ください。
// This function will do something with the parameters,
// the parameters should be good according to some rules.
myfunction(parameters)
{
var someThing = initializedWithSomething;
doSomethingWith(someThing);
doMoreWith(someThing);
endDoingThingsWith(someThing);
return someThing;
}
// This function will do some things to get started,
// the parameters should be good according to some rules.
doSomethingWith(parameters)
{
parameters.manipulateInSomeWay();
... etc ...
}
... etc ...
分離できないものについては、メソッドを抽出せず、コメントの下にコードを入力してください。
これは、コメントを最小限に留めるのに役立つ方法だと私が考えているものです。各行にコメントするのは実際には無意味です...マジック値の初期化や意味のある場所については、1行だけを文書化してください。
パラメータが多用される場合、それらはクラスのプライベートメンバーである必要があります。
答えは通常の「場合によります」だと思います。コードをコメントするだけのコメントコードは匂いです。桁違いに高速な不明瞭なアルゴリズムを使用しているため、コードにコメントを付けると、メンテナンスプログラマー（通常、私が書いてから6か月後）がコードを調べて何をしているのかを半日節約できます。
// Dear me in the future. Please, resolve this problem.
または
// You think this code was written by somebody else.
// No, it wasn't. You ([some name]) did it.
コードのコメントは間違いなく「コードの匂い」ではありません。この信念は、通常、コメントが古くなり（古くなり）、維持が困難になる可能性があるという事実から来ています。ただし、コードが特定の方法で何かを行っている理由を説明する適切なコメントがあると、メンテナンスにとって重要になります（通常は重要です）。
良いコメントは、コードが何をしているかを理解しやすくし、さらに重要なのは、なぜそれを特定の方法で行っているのかを理解しやすくすることです。コメントはプログラマが読むことを意図しており、明確かつ正確でなければなりません。理解しづらいコメントや不正確なコメントは、コメントがまったくなかった場合よりもはるかに優れています。
コードに明確で正確なコメントを追加することは、コードのセクションの「内容」と「理由」を理解するためにメモリに依存する必要がないことを意味します。これは、後でそのコードを見るとき、または誰かがあなたのコードを見る必要があるときに最も重要です。コメントはコードのテキストコンテンツの一部になるため、コメントは明確に記述されるだけでなく、優れた記述原則に従う必要があります。
良いコメントを書くには、コードの目的（理由ではなく、理由）を文書化し、コードの背後にある理由とロジックをできるだけ明確に示すようにします。理想的には、コメントはコードの作成と同時に書き込む必要があります。待っても、戻って追加することはおそらくないでしょう。
Sams Teach Yourself Visual C＃2010 in 24 Hours 、pp 348-349。
ライブラリ（サードパーティのライブラリ、またはコンパイラに付属のライブラリの両方）に存在する問題を回避するためにコードが特定の方法で記述されている場合は、コメントすることは理にかなっています。
また、将来のバージョンで変更する必要があるコードをコメント化したり、新しいバージョンのライブラリを使用したり、PHP4からPHP5に渡したりする場合などにも意味があります。
最もよく書かれた本でさえ、おそらく序文と章のタイトルがあります。十分に文書化されたコードのコメントは、高レベルの概念を説明し、コードがどのように編成されているかを説明するのに役立ちます。
名誉ある言及はアンチパターンです：
FLOSSライセンスのプリアンプが頻繁に使用されるというのが私の印象です代わりにファイルのドキュメント。 GPL/BSDLは、Niceフィラーテキストを作成します。その後、他のコメントブロックはめったに表示されません。
コードを説明するコメントを書くのは良くないという考えには同意しません。これは、コードにバグがあるという事実を完全に無視します。コメントなしで、コードdoesが何であるかは明らかかもしれません。コードが何であるかが明確になる可能性は低くなります想定実行する必要があります。コメントがなければ、結果が間違っているかどうか、またはそれらが誤って使用されているかどうかをどのようにして知ることができますか？
コメントは、コードのintentを説明する必要があります。そのため、間違いがあった場合、コメント+コードを読んでいる誰かがコードを見つける可能性があります。
私は通常、インラインコメントを書いていますbeforeコードを記述します。このようにして、私が何をしようとしてコードを書こうとしているのかが明確になり、何をしようとしているのかを本当に知らなくても、アルゴリズムで失われるのを減らすことができます。
私自身の質問で答えます。以下のコメントされていないコードでバグを見つけることができますか？
tl; dr：あなたのコードを保守する次の人はあなたほど神のようではないかもしれません。
[org 0x7c00]
main:
mov ah, 0x0e
mov bx, string
call strreverse
call print
stop:
jmp $
strreverse:
pusha
mov dx, bx
mov cx, 0
strreverse_Push:
mov al, [bx]
cmp al, 0
je strreverse_pop
Push ax
add bx, 1
add cx, 1
jmp strreverse_Push
strreverse_pop:
mov bx, dx
strreverse_pop_loop:
cmp cx, 0
je strreverse_end
pop ax
mov [bx], al
sub cx, 1
add bx, 1
jmp strreverse_pop_loop
strreverse_end:
popa
ret
print:
pusha
print_loop:
mov al, [bx]
cmp al, 1
je print_end
int 0x10
add bx, 1
jmp print_loop
print_end:
popa
ret
string:
db 'Boot up', 0
times 510 -( $ - $$ ) db 0
dw 0xaa55
誰かが1つの方法で700行にしても大丈夫だと思っているために付けられたコメントは匂いです。
あなたがコメントを入れないならあなたが知っているのでそこにあるコメントは、誰かが再び同じ間違いをするでしょう、再びにおいです。
一部のコード分析ツールは臭いも要求するため、コメントが付けられています。
everコメントを入れたり、他の開発者のために少しでも助けを書いたりしない人も、匂いがします。何人も書き留めないことに驚いていますが、その後振り返って、3か月前に何をしたか思い出せないことを認めます。私はドキュメントを書くのは好きではありませんが、同じことを何度も何度も繰り返し人々に伝えなければなりません。
コードとコメントのバランスを保つ必要があります...通常は、コードのブロックを再開するコメントを追加しようとします。私がコードを理解できないから（それもそうです）ではなく、自分のコードをより速く読み、重要なことが起こっている特定のセクションを見つけることができるからです。
とにかく、私自身の個人的な基準は「疑わしいときはコメントする」です。私には理解できない完全に暗号化された回線よりも冗長回線を使用することを好みます。しばらくすると、コードレビューのコメントをいつでも削除できます（通常は削除します）
また、コメントは、「注意！入力の形式がASCIIでない場合、このコードは変更する必要があります！」のような「警告」を追加するのに非常に役立ちます。
コードのコメントは非常に貧弱なスタートを切ると思います。最近のことはわかりませんが、学校でプログラミングを教えていたときに、「1から10までの数字を別々の行に出力するプログラムを書く。コードにコメントしてください」という性質の課題がありました。コードをコメントするのは良いことなので、コメントを追加しなかった場合はマークダウンされます。
しかし、そのような些細なプロセスについて何を言うべきでしょうか？だからあなたは古典を書くことになります
i++; // add one to the "i" counter.
まともな成績を得るために、そしてもしあなたが少しでもノーと思ったら、即座にコードコメントの非常に低い意見を形成します。
コードのコメントは良いことではありません。それはSOMETIMES NECESSARY THINGであり、トップの回答のThomas Owensは、それが必要な状況の優れた説明を提供します。ただし、これらの状況が宿題タイプの割り当てで発生することはほとんどありません。
多くの点で、コメントを追加することは最後の手段と考える必要があります。その場合、プログラミング言語のアクティブな部分では、言う必要のあることが明確に言えません。オブジェクトの命名は古くなる可能性がありますが、人間やコンピュータのさまざまなフィードバックの欠如メカニズムにより、コメントの維持を忘れがちになり、その結果、コメントはアクティブなコードよりもはるかに早く古くなります。そのため、選択が可能な場合は、コードを変更してわかりやすくすることを、不明確なコードにコメントで注釈を付けるよりも常に優先する必要があります。
これを読んで、数十年前に私が最初に読んだもの（長いリストから、コピーを取って保存されている）を思い出します。
本物のプログラマはコメントを書かない-書くのが難しかったなら、読むのは難しいはずだ
かなり古いにおいがします。
もちろんコメントはコードの匂いです...
すべてのプログラマーは私たち全員が最終的に 狂ってしまう を知っています。これは、作業量、デバッグ、または私たちが遭遇した単なる狂気のためです。
"これを行う！"あなたのプロジェクトマネージャーは言います。
あなたは「それはできません」と答えます。
彼らは「それなら私たちはそれをする誰かを見つけるでしょう」と言います。
あなたは、「OK、まあそれはできるかもしれません」と言います。
そして、次のX日、数週間、数ヶ月を費やして、それを理解しようとします。プロセス全体を通して、試行錯誤し、試行錯誤します。 私たちはすべてこれを行います。正解は、コメントするプログラマとコメントしないプログラマの2種類のプログラマがいるということです。
1）実行するものは、将来の参照用に文書化するか、機能しなかった失敗したルーチンをコメントアウトする（臭いは機能するものを見つけた後にそれらを削除しない）か、またはコメントでコードを分割することにより、自分の仕事を簡単にしますにフォーマットすると、読みやすくなり、理解しやすくなります。真剣に、私はそれらを責めることはできません。しかし、結局、それらはパチンと鳴り、それからあなたはこれを持っています：// dammit this code sucks! swear! curse! i hate it! i am going to write something here to vent my anger!!!!
2）スーパーヒーローになりすましていない、または 洞窟に住んでいる 。彼らは単に他人自身を無謀に無視するだけであり、コードや、それが将来どのような意味を持つ可能性があるかを気にする必要がありません。
誤解しないでください。変数と関数を自己文書化すると、これを完全に回避できます..およびtrust me十分なコードのクリーンアップを行うことはできません。しかし、単純な真実は、バックアップを保持している限り、[〜＃〜]常に[〜＃〜]コメントを削除できることです。
コメントとコードには大きな根本的な違いがあります。コメントは、人々がアイデアを他の人々に伝えるための手段ですが、コードは主にコンピュータ向けです。 「コード」には、命名やインデントなど、人間専用の多くの側面があります。しかし、コメントは人間によって、人間によって厳密に書かれています。
したがって、コメントを書くことは、人間によるコミュニケーションと同じくらい難しいです。作者は、聴衆が誰であるか、そしてどのような種類のテキストが必要かについて明確な概念を持っている必要があります。 10年後、20年後に誰があなたのコメントを読むのか、どうやって知ることができますか？その人が完全に異なる文化の出身である場合はどうなりますか？等、私は皆がこれを理解することを望みます。
私が住んでいる小さな同質文化のなかでさえ、アイデアを他の人に伝えるのはとても難しいです。偶然を除いて、人間のコミュニケーションは通常失敗します。
コードでsomeコメントを使用しないことはコードのにおいだと私は主張します。コードは可能な限り自己文書化する必要があることには同意しますが、コードが適切に記述されているかどうかに関係なく、意味のないコードが表示される特定の時点に到達します。以下の理由により、コメントが必須のビジネスアプリケーションのコードをいくつか見ました。
- あなたはケースバイケースで何かをする必要があり、そのための良いロジックはありません。
- 法律が変更されたときにコードを1〜2年で変更する可能性があり、それをすばやく見つけたい場合。
- コードが何をしているか理解していないので、誰かが過去にコードを編集しました。
また、会社のスタイルガイドは、特定の方法で何かを行うように指示する場合があります。関数内のコードのブロックが実行していることを概説するコメントが必要だと彼らが言った場合は、コメントを含めてください。
私はあなたの同僚に同意しなければなりません。私がコードをコメントする場合、私は常に[〜＃〜] i [〜＃〜]が理解できないのではないかと心配していることを常に言います自分自身コード将来的に。これは悪い兆候です。
私がコードにコメントを追加する他の唯一の理由は、意味をなさないように見える何かを呼び出すことです。
これらのコメントは通常、次のような形式を取ります。
//xxx what the heck is this doing??
または
// removed in version 2.0, but back for 2.1, now I'm taking out again
これが私の経験則です：
- コードを記述し、コードの短い要約を別のドキュメントに保存します。
- 他の作業を行うために、コードを数日間そのままにしておきます。
- コードに戻ります。何をすべきかすぐに理解できない場合は、ソースファイルに要約を追加します。
識字プログラミング テクニックについて同僚に説明します。
該当する場合は、関数の引数と戻りの単位、構造体フィールド、ローカル変数さえも示すコードコメントが非常に便利です。火星探査機を思い出してください！
いいえ、コメントはコードのにおいではなく、悪用される可能性があるツールにすぎません。
goodコメントの例：
//これはセンチメートル単位だと思います。さらに調査が必要です！
//これはXを行う賢い方法です
//リストはここで空でないことが保証されています
でも全然わからないコードは大きいコード臭い…
クリーンなコードで作業してください。
それが選択肢でない場合は、コメント付きの「汚い」コードを使用します
コメントのない汚いコードより。
言葉のほとんどは口から出されたものです。しかし、私はそれをすべて要約すると思います：コメントのポイントは、コードが何をしているかの高レベルの説明/説明を与えることです。
さらに、ここに私がコメントを使用する方法のいくつかの例があります：
- 見出しとして、コードのセクションの一般的な目的を示す
- 私がコードをどこから取得したかを注記し、それによって盗用を回避する
- 時々ブロックの終わりにあり、どのブロックが終わりかを思い出させる
- 疑わしいと思われるコードが意図したものであることを指摘する（たとえば、スイッチケースが失敗する奇妙な時間）
- アルゴリズムの背後にある数学を説明する
これまでのところ、このスレッドでは誰もこれを述べていません。
型名、変数名、関数名、メソッド名、コメントはコードに関するメタデータにすぎず、コンパイラーが生成するマシンコードとは何の関係もありません（もちろん、エクスポートされたシンボルとデバッグシンボルの名前は除きます）。
タイプ名と変数名はあなたの名詞であり、関数とメソッド名はあなたの動詞であり、これらはあなたが行うべきステップを説明しています。コメントはその他すべてのものです。
いくつかの例：
double temperature; // In Kelvins.
/**
* Returns true if ray hits the triangle
*/
bool castRayOnTriangle(Triangle t, Ray r)
{
//...
if (determinant == 0)
{
/* The ray and the triangle are parallel, no intersection possible.*/
return false;
}
//...
}
/* X algorithm. Visit http://en.wikipedia.org/... for details.*/
<implementation of something difficult to understand for the layman algorithm. >
コメントは、更新されない場合は廃止される可能性がありますが、変数と関数の名前も廃止される可能性があります。最近、C構造体のbufPtrフィールドに遭遇しました。これは、バッファーやポインターとは何の関係もありません。そして、デフレートされたデータを解凍しないinflateBuffer関数を見つけましたが、完全なGZIPファイルです...これらは古いコメントと同じくらい迷惑です。
チームでのプログラミングを検討する回答が多すぎるようには思えません。私は上級開発者であり、私が理解するのが簡単なことを説明することを目的としたコメントを書く傾向があります。
私はそれを死後のチームのコミュニケーションまたは教育の形と見なしています。チームが使用しているコードを確認することをお勧めしますが、理解を深めるための記述はまだ行っていません。
今週のいくつかの例（PHPコード）：
//Pattern for finding jpeg photos
//Case insensitive pattern for jpg and jpeg
const PATTERN_PHOTO = "*.{[jJ][pP][gG],[jJ][pP][eE][gG]}";
PATTERN_PHOTOは、コードの後半でそれが何をするかを説明するのに役立ちますが、コメントがなければ、この特定のパターンが何をしているのか、ジュニア開発者にとってどれほど明確でしょうか？
同じコードセット：
//Ignore . and .. directories in Linux
if($file != "." && $file != "..")
開発者がPHPを知っていることを期待していますが、ホスティングに使用しているLinux OSを理解しているわけではありません。
ですから、これらのコメントは、実際に書くのにかかる時間を最小限に抑えて、チーム全体の効率を実際に向上させるものだと思います。
- コードのしくみがわからないというだけで、コードを書き換えるケースは少なくなります。 「どういうふうになっているかわからなかったので直した」真剣に、私は以前これに対処しなければなりませんでした。
- 個々のコードについての質問は少なくなります。質問に1回だけ答えるには、通常、コードを調べて、コードに慣れるための時間が必要です。そして、時々私は数週間離れて複数の人から同じ質問をするでしょう。 （はい、それは上記の例のように単純なことになります）
- 他の開発者は自分で学ぶことを奨励され、指導されます。もし彼らが出会ったら
//Ignore . and .. directories in Linux彼らはおそらくGoogleに飛び乗り、突然Linuxを少し良く理解するでしょう。