コメントは、プログラムが何をしているのかと言うべきですか？ （フォースの発明者の口論に対する意見）
しばしば挑発的な Chuck Moore （- Forth 言語の発明者）は以下のアドバイスをしました[1]：
コメントは慎重に使用してください！ （私はそれは大歓迎です。）あなたが見たそのプログラム、つまりすべてのコメントが付いたプログラムを覚えていますか？それらすべてのコメントはどの程度役に立ちましたか？どのくらい早くあなたはそれらを読むのをやめましたか？プログラムは自己文書化され、アセンブラプログラムでさえあり、ニーモニックの助けがいくらかあります。次のように言っても意味がありません。
LA B . Load A with B実際、それはポジティブな悪いことをします：そのようなコメントを見つけたら、私はそれらを読むのをやめます-そして役立つコメントを見逃します。コメントが言うべきことは、プログラムが何をしているかです。とにかく指示からそれがどうやってやっているのかを理解しなければなりません。このようなコメントは大歓迎です：
COMMENT SEARCH FOR DAMAGED SHIPMENTS
コメントはなぜプログラムは何をしているのかと言うべきですか？
以下の回答に加えて、これら2つのProgrammers投稿は、追加の洞察を提供します。
参考文献
1. 問題指向言語のプログラミング 、セクション2.4の終わり。チャールズH.ムーア。書かれた〜1970年6月。
コメントは、プログラムが何をしているのかと言うべきですか？
確かにそうです。必ずしも多くのコメントが必要なわけではありませんが、コメントがあれば、WHYはいくつかの奇妙な周辺シナリオ以外で回答する価値のある唯一の質問です。推論は簡単です。私があなたのコードを良くも悪くも読んだら、プログラムが実行しているwhatがわかります。わかりませんなぜ。私が知らないことはほとんどありません。 WHYはしばしば、履歴、問題ドメインの奇妙な部分、またはサードパーティの依存関係のハッキングに基づいています。
「なぜ」という意味によって異なります。
高レベルの要件、ユーザーストーリーなどの情報を意味する場合、「いいえ」のコメントは「理由」を説明するのに適した場所ではありません。はるかに適切な場所は、コミット/プッシュメッセージです。理想的には、問題トラッカーのチケットの詳細な説明を指す必要があります。そして、明らかにあなたはいつでもチケットを指すコードにコメントを持つことができます。
一方、コードで行った小さなしかし明白ではない決定の非常に短い説明を意味する場合は、そのようなコメントが適切です。しかし、それは多かれ少なかれ、チャック・ムーアが「プログラムが実行していること」によって意味するものと同じです（「理由」は暗示されています）。
関連する質問：
私は、彼らが何をしているのかを明らかにするメソッド名によく適合する単一責任原則の強力な支持者です。なぜ少し厳しいのか。何が起こっているかを正当化するためにコメントが必要になるほどに実装が複雑である場合、後続の実行呼び出しの最中に、特定のコードが実行されている理由をコンテキスト化することは困難です。私の好みは、WHYをユーザーストーリーに任せ、コード自体を効果的にコメントできるように細かく保つことです。
なぜ非常に強力な質問に答えることができます。
自分で答えるのに問題がある場合は、おそらくコード設計を適切に検討しておらず、クラス/関数/何でもモチベーションを再考する必要があるかもしれません。なぜ明確かつ簡潔な質問に答えることができれば、クラスもおそらく明確かつ簡潔になります。
アドバイスの本質は、コンパイラーと人々の両方のためにコードを書くことであり、コードによって表現されるものを説明しないことです。
コードとコメントの冗長性により問題が発生します。 2人が同意しない場合、おそらく両方が間違っています。あなたがそれを2回書いて、それを2回読む必要があるならば、誰かはおそらくそれを2回支払った。
回答の中には、方法を説明するための反対票と、何を、なぜ説明するための賛成票があります。同意する。コードの一部に関連するコメント、またはおそらく、最小限の、まとまりのある、まとまりのあるクラスを作成するために使用できる根拠を説明するコメントは、有益です。コードの誰がいつソース管理システムで見つけることができます。ソース管理のコミットコメントは、システムの目的に向けた進化の理解と相関を示します。バグトラッカーとリンクすると、理由に関する多くの質問に答えることができます。
スコープと適用性はコメントに適したトピックです。懸念事項を適切な方法で分離する場合は、ネーミングとコメントを使用して、将来のメンテナを導く必要があります。契約によるプログラミング、アサーションの使用、および単体テストはすべて、ソフトウェアの意味と期待される動作を明確にすることの組み合わせです。
コード自体は、一部はコンピューター用、一部は人間用（メソッドと変数の名前）です。しかし、コメントは、将来的に他の人またはあなた自身のいずれかである人間のみを対象としています（私たちの記憶の性質上、現在あなたとは少し異なる人になります）。人間へのメッセージは、役立つ情報で構成されている場合に価値があります。なぜハッシュではなくソートされたリストを使用しているのかを説明すると、この機会が即座に見られるからといって、2年後に無効なコードを急いで置き換える可能性は低くなります。
コメントは、言語に精通しているプログラマにはすぐにはわからないコードの側面を説明する必要があります。次に、言語が提供する機能を使用して、必要なコメントの数を最小限に抑える必要があります。
私はこれで怒られますが、私の経験では、ほとんどの場合、答えは[〜＃〜] no [〜＃〜]です。
思考の糧：
あなたはエッセイを書いています。あなたはテキストの段落を書きます。次に、最初の段落の内容を説明する別の段落を書きますか？ありそうもない。プログラミングは、エッセイや小説を書くことと大きく異なりますか？一部のライター（プログラマー）は上手ですが、一部は下手です。プログラマーが人と機械のために書くとき、本の著者は人のために書く。私は、コードは人とマシンの両方のために書かれていると主張し、言います。そのため、ほとんどの場合、コードが何をするのかコメントする（説明する）必要はありません。
あなたが書いたコメントは常に役に立ち、意味がありますね。同僚が書いたコメントはどうですか？あなたが書いたコメントについて、彼らはどう思いますか？同僚のコメントが嫌いです。彼らも私のことが好きではないに違いない。何もかもコメントしなくなったのは良かった。
コメントを必要としない方法でコードをリファクタリング（名前の変更、再構成、再利用など）できないでしょうか。ほとんどの場合、それを行うことができます。そうでない場合は、コメントまたは回答にいくつかのコードスニペットを投稿してください。コミュニティがそれをリファクタリングして、さらにコメントする必要がないようにするのは興味深いでしょう。
不要なものを維持したいですか？私はしません。非公開APIで見たコメントのほとんどは不要です。
壊れているものにコメントすることがよくあります。壊れている。クラスはめちゃくちゃで、10の異なることをします。コメントするだけで、罪悪感が減ります。何かが壊れるたびに、人々は私のコメントを見て、それは彼らが気分を良くするでしょう。いいえ、ありません。悪いコードはコメントするのではなく、その場で修正する必要があります。すぐに実行しないと、後であなたや同僚が悩まされることになります。彼らがあなたについてどう思うかを推測しますか？
私は数年前からソフトウェアエンジニアとして働いており、「すべてをコメントする」から「まったくコメントしない」に移行しました。そうは言っても、私は：
- パブリックAPI、またはサードパーティに提供される任意のコードにコメントを付けます。そうでない場合、それらはおそらく苦情やサポートリクエストでスパムします。
- 正規表現。
- 本当に複雑なもの。すべてのフレームワークがあるので、本当に複雑なものに出くわすことはほとんどありません。
ここでの回答の1つは、コメントがないと、プログラムが実行している理由とは対照的に、プログラムが実行していることを簡単に確認できることを示しています。なぜ何かが行われているのかはコードに属していません。別のドキュメント、SharePoint、ブログ、ナプキンに含める必要がありますが、コードには含めないでください。