「コメントはコードの匂いです」[非公開]

私の同僚があると考えているすべてのイン・コードのコメント（つまり、いないのjavadocスタイルのメソッドやクラスのコメント）の使用があるコードのにおい。どう思いますか？

コメントがコードの実行内容を説明している場合のみ。

メソッドまたはブロックで何が起こっているかを知りたい場合は、コードを読みます。とにかく、与えられたプロジェクトに取り組んでいる開発者は、少なくとも開発言語に精通していて、書かれていることを読んで、それが何をしているのか理解できることを望みます。

極端な最適化の場合には、コードの実行内容を誰かが追跡するのを困難にする手法を使用している可能性があります。これらの場合、コメントを使用して、そのような最適化を行う理由だけでなく、コードが何をしているのかを説明することができます。良い経験則は、実装言語とプロジェクトに精通している誰か（または他の複数の人）にあなたのコードを見てもらうことです-彼らが理由と方法の両方を理解できない場合は、理由と方法。

ただし、コードで明確になっていないのは、あなたが何かをした理由です。他の人には明らかではないかもしれないアプローチをとる場合、あなたがした決定をした理由を説明するコメントが必要です。コードレビューのようなものまでコメントが必要であることに気付かないかもしれないと思うかもしれません、人々はあなたがなぜYではなくXをしたのかを知りたいです-あなたはそれを見る他のすべての人のためにコードで答えをキャプチャすることができます将来は。

ただし、最も重要なことは、コードを変更するときにコメントを変更することです。アルゴリズムを変更する場合は、YよりもアルゴリズムXを使用した理由でコメントを更新してください。古いコメントはさらに大きなコード臭です。

これは今のところ特に耳障りです。私は今週週末、研究アルゴリズム（実際には公開されていないもの）を実装する非常に名前がよく、非常にクリーンでコメントのないコードを見て過ごしました。私はそれに精通しており、私の隣に座っているのは発明者であり、コードは数年前に他の誰かによって書かれました。私たちはほとんどそれに従うことができませんでした。

同僚は明らかに十分な経験がありません。

コメントでは、方法ではなく、理由を説明する必要があります。

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)

あなたの同僚を異端者だと宣言します！私の異端者のブーツはどこにありますか？

強迫コメントが悪いとメンテナンスの頭痛である、とコメントなど、よく名前のメソッド、クラス、変数、のための代替ではない。しかし、時には入れて、なぜ何かがそれがある方法ですが、コードを維持しなければならない貧しい馬鹿のための非常に貴重なことができ半年で-特にその貧しい馬鹿があなたであるとき。

私が取り組んでいるコードからの実際のコメント：

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

コメントも維持し、同期しなければならないことを忘れないでください。古いコメントや間違ったコメントはひどい痛みになる可能性があります。また、一般的なルールとして、コメントしすぎると、プログラミングが不適切である可能性があります。

メソッドまたはプロセスを「コードのにおい」としてカテゴリー的に定義することは「熱心なにおい」です。この用語は新しい「有害と見なされる」ものになりつつあります。

これらすべてのことはガイドラインであることに注意してください。

他の回答の多くは、コメントがいつ正当化されるかに関して良いアドバイスを与えます。

個人的に私は非常に少ないコメントを使用します。非自明なプロセスの目的を説明し、数週間のチューニングを必要とするものを自分で変更することを検討している可能性のある人に臨時の死の脅威を残します。

幼稚園児がそれを理解できるまですべてをリファクタリングすることは、時間の効率的な使用ではない可能性が高く、おそらく、より簡潔なバージョンほどパフォーマンスが低下します。

コメントはランタイムに影響を与えないため、考慮すべき唯一のマイナスの問題はメンテナンスです。

場合によっては、適切なネーミング、リファクタリングなどの量がコメントを置き換えることができません。この実際の例を見てください（言語は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

ここでの主要な問題は、「コード臭」という用語の意味です。

多くの人々（私を含む）は、コードの匂いがエラーに近いもの、または少なくとも修正が必要なものであると理解しています。おそらく、あなたはそれを「アンチパターン」の同義語と考えています。

これは用語の意味ではありません！

コードの匂いのメタファーはWards Wikiに由来し、彼らは強調しています：

CodeSmellは、何かが間違っているかもしれないというヒントであり、確実性ではないことに注意してください。完全に優れたイディオムは、誤用されることが多いか、ほとんどの場合に機能するより単純な代替手段があるため、CodeSmellと見なされます。何かをCodeSmellと呼ぶことは攻撃ではありません。それは単に、より詳細な観察が必要であるという兆候です。

つまり、コメントがコード臭であることはどういう意味ですか？コメントが表示されたら、一時停止して考える必要があることを意味します：「うーん、何かが改善されるかもしれないというヒントを感じます」。おそらく、変数の名前を変更したり、「抽出メソッド」リファクタリングを実行したりできます。あるいは、実際にはコメントが最良のソリューションです。

それが、コメントがコードのにおいであるということです。

編集：私はちょうどこれらの2つの記事に困惑し、それは私よりもそれを説明しています：

• コード内の謝罪
• コメントが必要な場合

ルールは非常に簡単だと思います。完全に見知らぬ人があなたのコードを見ていると想像してください。あなたはおそらく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、348-349ページ。

ライブラリ（サードパーティライブラリ、またはコンパイラに付属するライブラリの両方）に存在する問題を回避するためにコードが特定の方法で記述されている場合は、コメントするのが理にかなっています。
また、将来のバージョンで変更する必要があるコード、または新しいバージョンのライブラリを使用するとき、またはPHP4からPHP5に渡すときなどにコメントすることも理にかなっています。

最もよく書かれた本でさえ、おそらく紹介と章のタイトルを持っています。よく文書化されたコード内のコメントは、高レベルの概念を説明し、コードがどのように編成されているかを説明するのに役立ちます。

名誉ある言及はアンチパターンです：

ファイルのドキュメントの代わりにFLOSSライセンスのプリアンプが頻繁に使用されることがあるという印象です。GPL / BSDLは素晴らしいフィラーテキストを作成しますが、その後、他のコメントブロックはめったに表示されません。

コードを説明するコメントを書くのは悪いという考えには同意しません。これは、コードにバグがあるという事実を完全に無視します。コメントなしでコードが何をするかは明らかかもしれません。これは、コードがされているものは明らかになりにくいのですはず行うこと。コメントがなければ、結果が間違っているのか、それとも間違って使用されているのかをどのように知っていますか？

コメントには、コードの意図を説明する必要があります。そのため、間違いがある場合は、コメント+コードを読んでいる人が見つけられる可能性があります。

私は通常、コードを書く前にインラインコメントを書くことに気づきます。このようにして、私がやろうとしているコードを書こうとしていることが明確になり、あなたが何をしようとしているのかを実際に知らなくても、アルゴリズムで迷子になることが少なくなります。

誰かが1つのメソッドに700行を入れても大丈夫だと思うために付けられたコメントは臭いです。

コメントを入力しないと、誰かが再び同じ間違いを犯すことを知っているため、そこにあるコメントは臭いです。

いくつかのコード分析ツールがそれも臭いだと要求しているので、コメントを入れました。

人々はありません、これまでのコメントに入れて、または他の開発者のために少しでも助けを書くも臭いです。物を書き留めない人が多いことに驚いていますが、それから振り返って、3か月前に何をしたか覚えていないことを認めます。私はドキュメントを書くのは好きではありませんが、人々に同じことを何度も何度も言わなければならないのが好きです。

私自身の質問で答えます。以下のコメント化されていないコードでバグを見つけることができますか？

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

コードとコメントのバランスを保つ必要があります...通常、コードのブロックを再開するコメントを追加しようとしています。コードを理解できないからではなく（まあ、それも）、自分のコードをより速く読み、重要なことが起こっている特定のセクションを見つけることができるからです。

とにかく、私自身の個人的な基準は「疑わしいときはコメント」です。私は理解できないであろう完全に不可解な回線よりも冗長な回線を好む。しばらくすると、コードレビューのコメントをいつでも削除できます（通常は削除します）

また、「注意してください！入力の形式がASCIIでない場合、このコードを変更する必要があります！」などの「警告」を追加すると、コメントが非常に役立ちます。

これを読んで、数十年前に（写真を撮って保存された長いリストから）最初に読んだものを思い出します。

本物のプログラマーはコメントを書かない

やや古い匂いがする。

コードのコメントは、非常に悪いスタートを切ると思います。最近はわかりませんが、学校でプログラミングを教えられたとき、「1から10の数字を別々の行に印刷するプログラムを書いてください。コードにコメントしてください」という性質の割り当てを受けました。コードにコメントを付けるのは良いことなので、コメントを追加しなかった場合はマークダウンされます。

しかし、そのような些細なプロセスについて何を言っているのでしょうか？だからあなたは古典を書くことになります

i++; // add one to the "i" counter.

まともな成績を得るためだけで、もしあなたが少しでもうるさいなら、コードコメントに対する非常に低い意見を即座に形成します。

コードのコメントは良いことではありません。それは時々必要なものであり、トップアンサーのトーマス・オーエンズは、それが必要な状況の優れた説明を提供します。ただし、これらの状況は宿題タイプの割り当てではめったに起こりません。

多くの点で、コメントを追加することは、プログラミング言語のアクティブな部分で何を言う必要があるかを明確に言えない場合、最後の手段の選択肢と見なすべきです。オブジェクトの命名は古くなる可能性がありますが、人間とコンピューターのさまざまなフィードバック不足メカニズムにより、コメントの維持を忘れやすくなり、その結果、コメントはアクティブコードよりもはるかに早く古くなってしまいます。そのため、選択が可能な場合、コードを変更して明確にすることは、不明確なコードにコメントを付けるよりも常に優先されるべきです。

もちろんコメントはコードの匂いです...

すべてのプログラマーは、作業量、デバッグ、または単に狂気に陥ったために、私たち全員が最終的に狂気に陥ることを知っています。

"これを行う！" プロジェクトマネージャーが言います。

「できません」と答えます。

彼らは、「それなら、他の誰かを見つけるでしょう」と言います。

あなたは「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）スーパーヒーローのふりをしていない人、または洞窟に住んでいる人。彼らは単に他人を無謀に無視しているだけであり、コードについてはあまり気にすることができません。

誤解しないでください。自己文書化変数と関数はこれを完全に回避することができます。そして、十分なコードのクリーンアップができないことを信じてください。しかし、単純な真実は、バックアップを保持している限り、常にコメントを削除できるということです。

あなたのコードでいくつかのコメントを使用しないことは、コードの匂いだと私は主張します。コードはできる限り自己文書化する必要があることに同意しますが、コードがどれだけうまく書かれていても意味をなさないコードが表示される特定のポイントに到達します。私は、コメントがほとんど必須であるビジネスアプリケーションでいくつかのコードを見てきました。

1. あなたはケースバイケースで何かをする必要があり、それに対する良いロジックはありません。
2. 法律が変更され、すぐに再び見つけたい場合、コードは1〜2年で変更される可能性があります。
3. 過去に誰かがコードを編集したのは、コードが何をしていたのか理解していないためです。

また、会社のスタイルガイドでは、特定の方法で何かを行うように指示される場合があります。関数内のコードブロックの実行内容を説明するコメントが必要だと言ったら、コメントを含めます。

コメントとコードには大きな根本的な違いがあります。コメントは、人々が他の人にアイデアを伝える手段であるのに対して、コードは主にコンピューターを対象としています。「コード」には、ネーミングやインデントなど、人間専用の多くの側面があります。しかし、コメントは人間によって厳密に書かれています。

したがって、コメントを書くことは、書かれた人間のコミュニケーションとまったく同じくらい難しいです！作家は、聴衆が誰であり、どのようなテキストが必要かについて明確な概念を持っている必要があります。10、20年後に誰があなたのコメントを読むのか、どうやって知ることができますか？その人がまったく異なる文化の出身である場合はどうなりますか？等これを皆が理解することを望みます。

私が住んでいる小さな均質な文化の中でさえ、他の人にアイデアを伝えるのはとても難しいです。偶然の場合を除き、人間のコミュニケーションは通常失敗します。

私はあなたの同僚に同意しなければなりません。私はいつも、私は自分のコードをコメントしている場合、それは私がいることを心配していることを意味していることを言う私が把握することができなくなり、私自身のコードを将来に。これは悪い兆候です。

コードにコメントを振りかける他の唯一の理由は、意味をなさないように見えるものを呼び出すことです。

これらのコメントは通常、次のような形式を取ります。

//xxx what the heck is this doing??

または

// removed in version 2.0, but back for 2.1, now I'm taking out again

該当する場合、関数の引数と戻り値の単位、構造体フィールド、さらにはローカル変数を与えるコードコメントは非常に便利です。火星オービターを忘れないでください！

私の経験則は次のとおりです。

• コードを記述し、コードの短い要約を別のドキュメントに保存します。
• 他の作業を行うには、コードを数日間そのままにしておきます。
• コードに戻ります。実行すべきことをすぐに理解できない場合は、ソースファイルに概要を追加します。

Literate Programmingテクニックについて同僚に教育します。

いいえ、コメントはコードの匂いではなく、悪用される可能性のある単なるツールです。

良いコメントの例：

//これはcm単位だと思います。さらに調査が必要です！

//これはXを行う賢い方法です

//リストはここで空でないことが保証されています