検索しましたが、探しているものが見つかりませんでした。この質問が既に質問されている場合は、お気軽にリンクしてください。

今月初めにこの投稿が行われました：

http://net.tutsplus.com/tutorials/php/why-youre-a-bad-php-programmer/

基本的には、コメントを書かないと悪いプログラマーになります。私の意見では、コードは記述的であり、コードが自己記述的でない場合を除き、ほとんどコメントを必要としないはずです。

与えられた例では

// Get the extension off the image filename  
$pieces = explode('.', $image_name);  
$extension = array_pop($pieces);  

著者は、このコードにはコメントを付けるべきだと述べました。私の個人的な意見では、コードは記述的な関数呼び出しである必要があります。

$extension = GetFileExtension($image_filename);

しかし、コメントでは誰かが実際にその提案をしました：

http://net.tutsplus.com/tutorials/php/why-youre-a-bad-php-programmer/comment-page-2/#comment-357130

著者は、コメンターは「それらの人々の1人」、すなわち、悪いプログラマーであると答えました。

自己記述型コードとコメント型コードについて、他の誰もが見ていることは何ですか？

私は自己文書化コードを書くことを好みます。このガイドはClean Codeです。

もちろん、これはコメントを決して使用してはならないという意味ではありません-それらには役割がありますが、私見では慎重に使用する必要があります。SOに関する私の以前のこの回答は、トピックに関する私の考えをより詳細に説明しています。

もちろん、@ Niphraが指摘したように、私がきれいだと信じていることは他の人に本当に理解できることを常に確認する価値があります。しかし、これも実践の問題です。ユニに戻ると、気まぐれによれば、すべてのコードエンティティに奇妙で面白い名前を使用しているために、不可解なコードを作成しました。私の先生が私の課題の1つを投げ返すまで、どのモジュールがメインであるかわからないことを丁寧に指摘していました:-)これは良い教訓でした。今日、私はチームメートから苦情をほとんど受けません。

コードが何をしているかを文書化するべきではありませんが、なぜそれを行っているのかを文書化する必要があります。

命名の裏技で理由と理由が明らかになることはないため、さまざまなコードの目的を説明するコメントを追加する必要があります。

他のすべてのコメントは安全に削除できます。

私は実際に自己記述的なコードを信じていません。あり、より読みやすいコードと少ない読み取り可能なコードは（原作者として）それのあなたの知識、それを読ん男、およびコード関数の知識は、言語に応じて、。しかし、いや、それでも...短いコメントで説明する必要があります。

私が今はっきりしているのは、私が完全に異なる何かを考えているときにコードのこの部分を再び使用する必要があるときに、私がおそらく1年で私にはその思考領域にいることは明確ではないということです。

だから、あなたのコードをコメントしてください。もちろんすべての行（良い天国、いいえ）ではありませんが、関数/サブルーチン/モジュール、または特に扱いにくい部分の上に数行のコメントを入れて、それが何をするかを簡単に伝えてください。1年か2年で自分に感謝します。

幸いなことに、この議論の両方の陣営がここに代表され、両方の賛否両論が述べられました。

どちらの陣営も議論が重複しており、実際にそれらのほとんどに同意していると信じています。

重複する引数

• コードは読み取り可能である必要があります。
• コメントは、コードとまったく同じことを言うべきではありませんが、必要に応じてさらなる洞察を与えます。
• すべての変数/関数名は、それらが何であるか/実行されているかを適切に表すために、よく考えてください。
• 重複コードは防止する必要があります。

現在、主な違いは、これらの引数のいくつかにどの程度の重みが付けられているかです。

自己記述型コード

• コメントは陳腐化する可能性があるため、間違ったコメントはコメントがないよりも悪いため、コメントの使用を最小限に抑えます。
• コメントはコードの複製です。コードで記述できるものはすべて、コードで記述する必要があります。

他のコメント

• コメントはコードより読みやすいです。平易な英語は何かを記述するのに優れています。

• 単純なコードはあいまいさを引き起こすことが多く、とにかくコメントする必要があります。これをコードで記述しようとすると、名前が長すぎます。さらに、この「余分な」情報に常に直面しているのは、初めて目にするときだけです。

どちらの陣営も非常に有効な論拠を持っていると思いますが、1つの問題を解決したからといって、1つの陣営を必死に追うべきではありません。

デモンストレーションのために、本Clean Codeでは、コードは一度しか呼び出されない多数の小さなメソッドに分割されています。メソッドは、コードを文書化する唯一の理由で作成されます（TDDがより簡単になります）。これにより、Function Hellが生成されます。コードは当初よりも読みにくくなり、リファクタリング中は、再利用可能なコードをカプセル化することは考えられませんでした。

一方、「コメントが良い」という理由だけで、すべての機能がコメント化されているAPIをよく目にします。コメントすべきだったものはまだそうではありません。

「ごめんなさい、あなたのあの男」

彼がコメントを好まないのはなぜだろうか：P

真剣に、コーディングは芸術のようなものであり、そのような抜本的な発言を正直に行うことができません。コメントが必要な場合もあれば、名前の付いたより良い関数が必要な場合もあります。通常両方。

リテラシープログラミングを極端なスタイルとして探します。

短く、より良く、正しい答え

よく書かれた「自己文書化されたコード」が必要なのはアンチパターンであり、「なぜ」を説明するコメントの例外を作成する場合でも死ぬはずです。それは、プログラマーがそれを一見して取得するのに十分な明確なアルゴリズムのすべてのコードを常に書くことができるという神話です（または、リファクタリングや組織の時間を必要としません）。さらに重要なことは、多くの場合、明確なコードを書くと考えるプログラマーはそうではないということです。

コメントよりもはるかに優れた答えは、「理由」を説明するためにのみ使用する必要があります。

• 「なぜ」を説明する（もちろん）
• コードが複雑であるか、目的が不明であり、さらに単純化することができない、またはする価値がない場合にのみ、個々の行で「何」を説明する
• 理解をスピードアップし、必要なものを見つけるためのコードブロックの「何」を説明する

バックアップの説明

人々は、コメントを使用する唯一の理由はコード行の意味を説明することであると誤って考えています。真実は、コードをコメント化する大きな目的は、コードをより速くすることであるコードをひと目で確認して、探しているものを見つけることができます。後でコードに戻ったり、他の人のコードを読んだりすると、よく書かれたコードのセクションを読んで理解できますが、上部のコメントを読んでコードのそのセクションが何をするかを言うのが速くて簡単ではありませんそれが私が探しているものではない場合は完全にスキップしますか？いくつかのコメントを見て機能全体を理解できるのであれば、なぜそれがうまく書かれていても、そこに座ってコードを理解するのですか？だから私たちは関数に説明的な名前を使用しています-私の関数に説明的な名前を使用する必要がないと言う人はいません。

たとえば、他の人の関数を調べている場合、コードを1行ずつ実行して何をしているのかを簡単に確認したり、関数全体で3つのコメントを一目で確認して、関数が何をしているか、どこでやってる？

別のアンチパターンは、コードをコメントするための関数の過剰使用です。適切な名前の関数はコード文書化の重要な部分ですが、プログラマーは文書化の目的で他のどこにも使用されないコードを2〜3行分離することがあります。コメントを過度に使用するよりも、機能を過度に使用する方が良いのはなぜですか そのような関数を使用することは、GOTOステートメントを受け入れることと同じです。スパゲッティコードが作成されるので、これを追うのは面倒です。

基本的に、人々が絶えずコードを共有していて、常にコードを完璧にする時間がないというエンタープライズ環境で作業するとき、いくつかの良いコメントは時間とフラストレーションを節約できます。そして、覚えておいてください、あなたは光速でコードを読むことができる第一人者かもしれませんが、おそらくあなたのオフィスの全員がそうではないでしょう。

まあ、あなたはあなたにとって明白な、または「自己文書化」されている何かを覚えておく必要があります。だから私はすべてについてコメントします。

さて、自己文書化コードのことは、その関数内で、あなたが見つけるだろうということです：

$pieces = explode('.', $image_name);  
$extension = array_pop($pieces);  

関数名は2行しかないため、関数名がある場合は自明です。事態がさら​​に複雑になった場合、関数内のコードの数行ごとにわかりやすい名前を付けるか、必要に応じてコメントを使用する必要があります。

and / andの代わりにor / orである理由を理解できませんでした。はい、可能な限り自己文書化するコードを作成し、はい、そうでなければかなり不明瞭になる部分にコメントを追加します。

コメントと自己文書化されたクリーンコードは異なります。コードはすべて物事を行う方法についてです。そしてコメントは、あなたの言語が何であれ、コードでは説明できないwhy部分をカバーするべきです。また、言語が非常に限られており、契約も静的な仕様もアサーションさえも持っていない場合、コメントはコードの境界の問題をカバーする必要があります。

その場合、記述関数を作成するのは簡単です。しかし、私は自分のコードが自己文書化されていると信じていた優秀なプログラマーによって作成された多くのコードを読みました。

$ extension = GetFileExtension（$ image_name）;

あなたの例に戻るために、私はそれに画像名の配列を送ることができますか、それは1つの画像だけを取りますか？あらゆる種類のファイルをサポートしていますか、それとも一部のみをサポートしていますか？それは私のために文字列を保護しますか、または私はそれをしなければなりませんか？ファイルの種類が存在しない場合、通知されますか？

もちろん、私はこれを少し伸ばしています。しかし、audio_bandwidthとvideo_bandwidthは自己文書化された名前だと信じていたプログラマを覚えています。オーディオはバイト単位で、ビデオはキロバイト単位で表現する必要がありました。それを理解するのに多くの時間を費やしました。

一方は他方を除外しません。コードは自己コメントですが、自己コメントコードが何をするのかを説明するために定期的なコメントが必要な場合があります。

私はその記事に同意せず、ある程度あなたに同意します。適切なメソッド名、適切な変数名、単一のことを行う小さなメソッドを使用する場合、コードは簡単に理解できるはずです。

賢いコードは恐ろしい読み取りと保守なので、賢くならないようにしてください。キーワード：メンテナンス！

私の意見では、コメントは何ではなく理由を説明すべきだということです。この架空の完璧な世界では、コードは読みやすいように十分にきれいであり、何をしているのかを説明する必要はありませんが、なぜこのようにしたのか、そのようにしたのかを覚えておいてください。

ソース管理システムを使用している場合は、コミットメッセージを使用して、特定の時間に何をしたか、さらに重要なのはなぜかを全員（および自分自身）に知らせることができます。

ドキュメントを避けたいのと同じように、コメントを書くことは避けたいでしょう。プログラミング言語自体に関して言えば、誰もが（ほぼ）同じ語彙と構文のセットから操作しています。

アプリが特定のドメイン向けである場合、全員が共通の語彙に同意したり、確立したりすることは困難です。略語や広範な専門用語を避けるように教えられていますが、私はそれを呼ぶつもりです

EBITDA

ではなく

EquityBeforeInterestTaxes減価償却費

一方がわからない場合、おそらくもう一方は理解できないでしょう。会社に一般的でない実装がある場合、コメントはドメインでの経験があるかもしれない次のプログラマに役立ちますが、この特定の企業には役立ちません（これは単に事態をより複雑にします）。

ドキュメントとコードの表現性を区別する必要があると思います。

コードをデバッグまたはレビューするときは、本を読んでいません。ほとんどの場合、メソッドからメソッドにジャンプして、実行時に何が起こっているかについての基本的な理解を得るために頭の中で素早く接続したいだけです。コードに関する文書化ではなく、表現力そのプロセスで重要は、コードに関するコード署名のであり、それらをすぐに識別して独自の内部呼び出しスタックに追加できるほど有意義である能力です。その時点で、私たちの脳（少なくとも、私の脳はそのように動作します;））は、大きなコメントブロックを助けではなくノイズと見なす傾向があります。したがって、ここでは1行のコメント、またはさらに良いことに、自己記述的なメソッド名とオブジェクト名で十分です。

特定のクラスまたは機能の「本を読みたい」場合は、ユニットテストを使用することをお勧めします。適切に設計された単体テストは、本来は意図を明らかにし、最も厚いコメントブロックよりもはるかに多くの文書化（つまり、説明、詳細）です。実際のコードに対するこれらの期待。合格したテストは、それが主張するものが真実であることを証明するため、ドキュメントの点でどのコメントよりも100倍信頼性があります。

一部のコードは自己文書化されておらず、その部分を理解してテストした仲間の人間からのコメントが必要です。私が下に持っているものはそれを理解するのに十分ではありません、と思います。

//
// iterative version
//
Node* ReverseList( Node ** List ) 
{

  Node *temp1 = *List;
  Node * temp2 = NULL;
  Node * temp3 = NULL;

  while ( temp1 )
  {
    *List = temp1; //set the head to last node 
    temp2= temp1->pNext; // save the next ptr in temp2
    temp1->pNext = temp3; // change next to privous
    temp3 = temp1;
    temp1 = temp2;
  }

  return *List;
}

ほとんどのコードは完全に文書化されないと思うので、私は一般的に、コメントが不明確な自己文書化コードを書くことを好みます。

大学では、英語でコードのすべての行をコメントで言い換えることを教えられました（おそらく、何かをコピーして貼り付けて最高のものを期待するのではなく、実際にコードが何をするのかを理解する習慣を身に付けるためです）。

個人的に、あなたのコードから地獄を散らかし、それを減らすと思いますそれが単なるコメントまたは単なるコードである場合よりも読み。私はC＃コーダーであり、常にコメントを書くのは、「トリプルスラッシュ」コメントブロックのみで、IntelliSenseドキュメントに戻されます。何かを行う特定の方法について特に罪悪感を感じている場合、または特に不可解に見える場合は、さらに説明しますが、それはそれについてです。

IMO：自己文書化コードとは、変数名とメソッド名に意味のあるコンテキスト名が付けられたコードで、その目的を説明するものです。

コードを何度も再訪しても、ドメインを知っている人に意図を明確にする方法をまだ見つけていない場合。関数を書き直してください。結局、それは10〜20行以下です。とにかく関数をより長く書き換える場合は長くなり、それが読めない理由の一部です:)リンスリピート

まれに、コードが何をしているのかまだ不明であり、同僚に助けを求めることを忘れていません。それでは、あなたが書いているカーネルコードだから、Linuxの進化を助けてくれてありがとう。上からすすぎ繰り返しない場合:)

コメントを書いてはいけません

Code Complete 2nd edition、pg 128-129をご覧ください。

抽象データ型は、この難問からあなたを救います。自己文書化コードは行く方法です。コメントは便利ですが、

低レベルの実装ではなく、実際のエンティティ

コメントの使用を避けることができます。

コメントに関する1つのことは、コメントを1回書くだけですが、関数を実装するときは表示されず、関数を変更するときにのみ表示されることです。

コメントは、Delphi 2009+またはJavaDocが機能する方法でIDEによって解釈される場合に非常に役立ちますが、それは構造化マークアップ言語に近いため、ドキュメントをプログラミングしているという意味では非常に賢明です。

私は、コードはそれ自体を文書化しないという信念を信じています、なぜならあなたは世界で最高のプログラマーになる可能性があるからです（Ada）あなたのコードがそれをどのように行っているか、あなた自身と他の人を将来支援するつもりです。

コメントは必須です。あなたがコードを書くとき、あなたはあなたの現在のニーズのために書いているだけでなく、あなたのコードを読まなければならない将来の人々のためにも書いているので、wtfを理解していて、あなたは何をしているのか、そしてなぜそれを修正するのか。

コーディング/プログラミングの際にこれを念頭に置いているのですか？

私が取り組んでいるこのコードの将来のコーダーのためにこれを理解しやすく変更するにはどうすればよいですか？あなたは良い仕事をしているでしょう。それに失敗すると、他の人がコードを変更するのを難しくするだけで、決してそうではないと想像しないでください、それはまれです...

私の仕事のほとんどで、私は常に他の人のコードを修正しなければならず、最も恐ろしく書かれていて、文書化が不十分でした。

したがって、コードド​​キュメントを自分自身と考える習慣は、デューデリジェンスを行っていないだけです。

プログラマーとして、私たちは、経験の浅いプログラマーに完全に似ているように見えるかもしれないが、習慣を持たなければならない自己規律を実践しなければなりません。または、数か月後、数か月後の独自のコードを見ることさえできます。

http://thedailywtf.comをチェックしてください。彼らは、デューデリジェンスを行わなかったプログラマーについてのユーモラスでありながら本当の話をたくさん持っています。