自己文書化コードとは何ですか？それは十分に文書化されたコードを置き換えることができますか？[閉まっている]

私の同僚には、彼のコードにはコメントは不要で、「自己文書化」であると主張しています。

私は彼のコードを確認しましたが、他の人が作成したコードよりも明確ですが、自己文書化コードが完全かつ有用であり、コメント化および文書化されたコードであることにまだ同意しません。

彼の見方を理解してください。

• 自己文書化コードとは
• よくコメントされ、文書化されたコードを本当に置き換えることができますか
• 十分に文書化され、コメントされたコードよりも優れている状況はありますか
• コードがコメントなしで自己文書化できない例はありますか

多分それは私自身の制限だけかもしれませんが、それがどのように良い習慣になることができるかはわかりません。

これは議論を意図したものではありません-コメントと文書化されたコードが高い優先度である理由を挙げないでください-これを示す多くのリソースがありますが、それらは私の仲間には説得力がありません。そうでなければ彼を説得するには、彼の見方をより完全に理解する必要があると思います。必要に応じて新しい質問を開始しますが、ここでは議論しないでください。

うわぁ、素早い対応！ここで他のすべての回答と大きく異なる場合を除き、既存の回答をすべて読み、新しい回答を追加するのではなく、回答にコメントを入力してください。

また、自己文書化コードに対して異議を唱えている人たち-これは主に、自己文書化コードエバンジェリストの視点（つまり、肯定的な側面）を理解するのに役立ちます。あなたが話題に留まらない場合、他の人があなたに反対票を投じることを期待しています。

私の意見では、どのコードも自己文書化する必要があります。自己文書化された適切なコードでは、すべての識別子（変数、メソッド、クラス）に明確な意味の名前があるため、すべての行を説明する必要はありません。コメントが必要以上に多いと、実際にはコードが読みにくく（！）なるため、同僚が

• すべてのクラス、メンバー、タイプ、およびメソッドのドキュメントコメント（Doxygen、JavaDoc、XMLコメントなど）を書き込み、かつ
• 自己文書化されていないコードの部分に明確にコメントし、かつ
• コードのブロックごとにコメントを書き込んで、インテント、またはより高い抽象化レベルでのコードの動作を説明します（つまり、ディレクトリ内のすべてのファイルをループする代わりに、10 MBより大きいすべてのファイルを見つけ、ファイルサイズが10より大きいかどうかをテストしますMB、trueの場合は利回りを返す）

私の意見では、彼のコードとドキュメントは問題ありません。自己文書化されたコードは、コメントがないことを意味するのではなく、不必要なコメントがないことを意味することに注意してください。ただし、コード（コメントとドキュメントのコメントを含む）を読むことにより、コードの機能と理由を即座に理解できるはずです。「自己文書化」コードは、コメント付きコードよりも理解に時間がかかる場合、実際には自己文書化されていません。

これはコメントとコードに関するものなので、実際のコードをいくつか見てみましょう。この典型的なコードを比較してください：

float a, b, c; a=9.81; b=5; c= .5*a*(b^2);

何が行われているかを示すこの自己文書化コードに：

const float gravitationalForce = 9.81;
float timeInSeconds = 5;
float displacement = (1 / 2) * gravitationalForce * (timeInSeconds ^ 2);

そして、この文書化されたコードに、なぜそれが行われているのかをよりよく説明します：

/* compute displacement with Newton's equation x = vₒt + ½at² */
const float gravitationalForce = 9.81;
float timeInSeconds = 5;
float displacement = (1 / 2) * gravitationalForce * (timeInSeconds ^ 2);

そして、必要なコメントがゼロのドキュメンテーションとしてのコードの最終バージョン：

float computeDisplacement(float timeInSeconds) {
    const float gravitationalForce = 9.81;
    float displacement = (1 / 2) * gravitationalForce * (timeInSeconds ^ 2);
    return displacement;
}

以下は、不適切なコメントスタイルの例です。

const float a = 9.81; //gravitational force
float b = 5; //time in seconds
float c = (1/2)*a*(b^2) //multiply the time and gravity together to get displacement.

最後の例では、代わりに変数に説明的な名前を付ける必要がある場合にコメントを使用し、操作が何であるかが明確にわかる場合に操作の結果を要約しています。私はいつでもこれよりも自己文書化された2番目の例を好むと思います。おそらく、あなたが友人が自己文書化されたコードを言っているときにそれについて話しているのです。

それはあなたがやっていることの文脈に依存すると私は言うでしょう。私にとっては、この場合は自己文書化されたコードでおそらく十分ですが、実行の背後にある方法（この例では方程式）の詳細を説明するコメントも役に立ちます。

コード自体は常にコードの機能の最新の説明になりますが、私の意見では、コメントの最も重要な側面であるインテントを説明することは非常に困難です。それが適切に書かれていれば、コードが何をしているかはすでにわかっています。なぜ地球上でそれが行われるのかを知る必要があるだけです。

誰かがかつて言った

1）理解しにくいコードに対してのみコメントを記述します。
2）理解しにくいコードを書かないようにしてください。

「自己文書化」コードの背後にある考え方は、コード内の実際のプログラムロジックは、コードを読んでいる人にコードが何をしているのかだけでなく、なぜそれをしているのかを説明するのに十分明白であるということです。

私の意見では、真の自己文書化コードのアイデアは神話です。コードは何が起こっているかの背後にあるロジックを教えてくれますが、特に問題を解決する方法が複数ある場合は特に、それが特定の方法で行われている理由を説明できません。その理由だけで、十分にコメントされたコードを置き換えることはできません。

特定のコード行が自己文書化されているかどうかを問うのは妥当だと思いますが、結局、コードスライスの構造と機能を理解していなければ、ほとんどの場合、コメントは役に立ちません。たとえば、amdfanの「正しくコメントされた」コードのスライスを見てみましょう。

/* compute displacement with Newton's equation x = v0t + ½at^2 */
const float gravitationalForce = 9.81;
float timeInSeconds = 5;
float displacement = (1 / 2) * gravitationalForce * (timeInSeconds ^ 2);

このコードは問題ありませんが、以下はほとんどの最新のソフトウェアシステムで同様に有益であり、ニュートン計算の使用は他の物理パラダイムがより適切である場合に変更される可能性がある選択肢であることを明確に認識しています。

const float accelerationDueToGravity = 9.81;
float timeInSeconds = 5;
float displacement = NewtonianPhysics.CalculateDisplacement(accelerationDueToGravity, timeInSeconds);

私自身の個人的な経験では、コメントが絶対に必要な「通常の」コーディング状況はほとんどありません。たとえば、自分のアルゴリズムをローリングする頻度はどのくらいですか？基本的に、他のすべてはシステムを構造化することです。そのため、コーダーは使用中の構造と、それらの特定の構造を使用するようにシステムを駆り立てた選択肢を理解できます。

私はこれをどこから得たのか忘れていますが、

プログラム内のすべてのコメントは、読者への謝罪のようなものです。「コードが不透明で、見ただけでは理解できないのが残念です。」私たちは自分たちが完璧ではないことを受け入れなければなりませんが、完璧になるように努力し、必要なときに謝罪を正しく行います。

まず、同僚のコードが実際に見た他のコードよりも明確であると聞いて良かったです。それは彼がコードをコメントするのが面倒すぎて言い訳としておそらく「自己文書化」を使用していないことを意味します。

自己文書化コードは、情報に通じた読者が何をしているかを理解するためにフリーテキストのコメントを必要としないコードです。たとえば、次のコードは自己文書化されています。

print "Hello, World!"

これもそうです：

factorial n = product [1..n]

これもそうです：

from BeautifulSoup import BeautifulSoup, Tag

def replace_a_href_with_span(soup):
    links = soup.findAll("a")
    for link in links:
        tag = Tag(soup, "span", [("class", "looksLikeLink")])
        tag.contents = link.contents
        link.replaceWith(tag)

さて、この「情報に通じた読者」という考えは、非常に主観的で状況に応じたものです。あなたまたは他の誰かがあなたの同僚のコードをフォローするのに問題を抱えているなら、彼は情報を得た読者の彼の考えを再評価するためにうまくいくでしょう。コードの自己文書化を呼び出すには、使用する言語とライブラリにある程度の知識が必要です。

「自己文書化コード」を書くために私が見た最良の議論は、それが書かれているときにフリーテキスト注釈がコードに同意しないという問題を回避することです。最高の批判は、コードはそれ自体が何をどのように行っているかを説明できる一方で、何かが特定の方法で行われている理由を説明できないことです。

自己文書化コードは「DRY」（Do n't Repeat Yourself）の良い例です。コード自体の中にある、またはその可能性があるコメントの情報を複製しないでください。

変数の用途を説明するのではなく、変数の名前を変更します。

コードの短いスニペットが何をするかを説明するのではなく、それをメソッドに抽出し、説明的な名前を付けます（おそらくコメントテキストの短縮版です）。

複雑なテストが何をするのかを説明するのではなく、それもメソッドに抽出して適切な名前を付けます。

等。

この後、あまり説明を必要としないコードで終了し、それ自体が説明されるので、コード内の情報を繰り返すだけのコメントを削除する必要があります。

これは、コメントがないことを意味するのではなく、意図に関する情報（「理由」）など、コードに入力できない情報があります。理想的なケースでは、コードとコメントは互いに補完し合っており、それぞれが他の情報を複製せずに一意の説明値を追加しています。

自己文書化コードは良い習慣であり、適切に行われれば、あまり多くのコメントを読むことなく、コードの意味を簡単に伝えることができます。特に、ドメインがチームの全員によって十分に理解されている状況では。

そうは言っても、コメントは新規参入者やテスターに​​とって、あるいはドキュメント/ヘルプファイルを生成するために非常に役立ちます。

自己文書化コード+必要なコメントは、チーム全体の人々を助けるのに大いに役立ちます。

順番に：

• 自己文書化コードは、読者にその意図を明確に表すコードです。
• 完全にではありません。コメントは、特定の戦略が選択された理由についての解説に常に役立ちます。ただし、コードのセクションで何が行われているかを説明するコメントは、自己文書化が不十分であり、リファクタリングを使用できるコードを示しています。
• コメントはうそをつき、古くなります。コードは常に、真実を伝える可能性が高いことを伝えます。
• コメントなしではコードの内容を十分に明確にできない場合を見たことがありません。ただし、前に述べたように、理由についてのコメントを含めることが必要または役立つ場合があります。

ただし、真に自己文書化するコードには、多くの自己規律とチーム規律があることに注意することが重要です。より宣言的にプログラミングする方法を学ぶ必要があります。また、非常に謙虚で、「巧妙な」コードを避けて、誰でも書けるように明白なコードを支持する必要があります。

「自己文書化コード」を読むと、それが何をしているのかがわかりますが、なぜ特定の方法でそれが実行されているのか常に推測できるとは限りません。

ビジネスロジック、セキュリティ、ユーザーの要求など、プログラミング以外の制約がたくさんあります。

メンテナンスを行うとき、それらのバックゴーランド情報は非常に重要になります。

私の塩ひとつまみ...

まず、次のスニペットを検討してください。

/**
 * Sets the value of foobar.
 *
 * @foobar is the new vaue of foobar.
 */
 public void setFoobar(Object foobar) {
     this.foobar = foobar;
 }

この例では、3行のコードごとに5行のコメントがあります。さらに悪いことに、コメントを読んでも、コードを読んでも見えないものは追加されません。このような10のメソッドがある場合、「コメント失明」を取得し、パターンから逸脱する1つのメソッドに気付かない場合があります。

もちろん、より良いバージョンは次のようになります：

/**
 * The serialization of the foobar object is used to synchronize the qux task.
 * The default value is unique instance, override if needed.
 */
 public void setFoobar(Object foobar) {
     this.foobar = foobar;
 }

それでも、ささいなコードのために、私はコメントを好まない。意図と全体的な組織は、コード外の別のドキュメントでよりよく説明されています。

違いは、「何を」と「どのように」の間です。

• ルーチンが行う「内容」を文書化する必要があります。
• 特別な場合（たとえば、特定のアルゴリズムに関する論文を参照）を除いて、「方法」を文書化しないでください。自己文書化する必要があります。

同僚に指摘したいことの1つは、他の代替アプローチが検討されて破棄された場合、彼のコードがどのように自己文書化されていても、その情報でコードにコメントしない限り、その情報は失われるということです。時々、代替案が検討されたこと、そしてなぜそれが反対に決定され、コードのコメントが長期にわたって存続する可能性が最も高いかを知ることも同様に重要です。

私が働いていた会社で、プログラマーの一人が彼女のモニターの上部に引っかかっていました。

「それを維持する人があなたがどこに住んでいるかを知っている殺人狂信者であるかのようにあなたのコードを文書化してください。」

自己文書化コードは通常、コードが何をしているかと正確に一致する変数名を使用するため、何が起こっているのかを簡単に理解できます。

ただし、そのような「自己文書化コード」がコメントを置き換えることはありません。ときにはコードが複雑すぎて、特に保守性の点で、自己文書化コードでは不十分な場合があります。

私はかつてこの理論をしっかりと信じていた教授がいました。実際、彼が今まで覚えたことのある最高のことは「コメントは弱虫のためのものです」
というものでした。
ただし、コードで何が行われているのかは理解できても、経験の浅い誰かがあなたの後ろに来て、何が起こっているのか理解できない場合があります。これはコメントが重要になるときです。重要ではないと私たちは何度も知っていますが、コメントが不要なケースはほとんどありません。

1981年にTeXのドナルドE.クヌースによって開発された技術である「文芸的プログラミング」と「コンピュータプログラミングの芸術」で有名になった人が誰もいないことに驚いています。

前提は単純です：コードは人間が理解する必要があり、コメントはコンパイラーによって捨てられるだけなので、プログラミング言語の要件に縛られずに、コードの意図の完全なテキストによる説明をすべての人に与えてみませんか？ 、人間の読者のためとコンパイラのための純粋なコード。

文芸的プログラミングツールは、どの部分がソースで何がテキストであるかをツールに指示するドキュメントの特別なマークアップを提供することでこれを行います。プログラムは後でソースコード部分をドキュメントから取り除き、コードファイルをアセンブルします。

ウェブで例を見つけました：http : //moonflare.com/code/select/select.nwまたはHTMLバージョンhttp://moonflare.com/code/select/select.html

図書館でクヌースの本を見つけた場合（ドナルドE.クヌース、文芸プログラミング、カリフォルニア州スタンフォード：言語と情報の研究センター、1992年、CSLI講義ノート、第27号）を読む必要があります。

これは自己文書化されたコードであり、推論などがすべて含まれています。素敵なドキュメントを作成することもできますが、それ以外はすべてよく書かれたコメントです。

私は多くの有効な答えにもう1つの視点を提供したいと思います。

ソースコードとは？プログラミング言語とは何ですか？

マシンはソースコードを必要としません。彼らは幸せな実行中のアセンブリです。プログラミング言語は私たちの利益のためです。アセンブリを記述したくありません。私たちは何を書いているのかを理解する必要があります。プログラミングはコードを書くことです。

あなたが書いたものを読めるようにすべきですか？

ソースコードは人間の言語で書かれていません。試されましたが（たとえばFORTRAN）、完全に成功しているわけではありません。

ソースコードに曖昧さはありません。そのため、テキストよりも多くの構造を配置する必要があります。テキストはコンテキストでのみ機能します。これは、テキストを使用するときに当たり前のことです。ソースコードのコンテキストは常に露骨です。C＃で「使用」することを考えてください。

ほとんどのプログラミング言語には冗長性があるため、首尾一貫していないときにコンパイラーがキャッチできます。他の言語はより多くの推論を使用し、その冗長性を排除しようとします。

タイプ名、メソッド名、変数名は、コンピューターでは必要ありません。これらは参照用に使用されます。コンパイラはセマンティクスを理解していません。それは私たちが使用するためのものです。

プログラミング言語は、人と機械の間の言語的橋渡しです。それは私たちにとって書き込み可能で、読みやすいものでなければなりません。二次的な要求は、それを私たちが読めるようにすることです。許容されるセマンティクスが得意で、コードの構造が得意であれば、ソースコードは私たちにとっても読みやすいはずです。最高のコードはコメントを必要としません。

しかし、すべてのプロジェクトには複雑さが潜んでおり、複雑さをどこに置くか、どのラクダを飲み込むかを常に決定する必要があります。それらはコメントを使用する場所です。

自己文書化コードは問題を簡単に除外するものであり、時間の経過とともにコード、コメント、および文書が分岐します。そして、明確なコードを書くことは規律の要素です（あなたが自分自身にそれを厳格にしている場合）

私にとって、これらは私が従おうとする規則です：

• コードは可能な限り読みやすく、読みやすくする必要があります。
• コメントには、私が取った設計上の決定の理由を記載する必要があります。たとえば、なぜこのアルゴリズムを使用するのか、またはコードの制限など、次の場合は機能しません...（これはコードのコントラクト/アサーションで処理する必要があります）（通常関数/プロシージャ内）。
• 文書には、使用法（呼び出しを含む）、副作用、可能な戻り値をリストする必要があります。jDocやxmlDocなどのツールを使用してコードから抽出できます。したがって、通常は関数/プロシージャの外側にありますが、記述されているコードに近いものです。

これは、コードを文書化する3つの手段すべてが密接に関連しているため、コードが変更されたときに変更される可能性が高くなりますが、それらの表現が重複することはありません。

いわゆる自己文書化コードの本当の問題は、それが実際に行うことを伝えることです。一部のコメントは、誰かがコードをよりよく理解するのに役立つ場合があります（たとえば、アルゴリズムのステップなど）。これはある程度冗長であり、ピアを説得することはできないでしょう。

ただし、ドキュメンテーションで本当に重要なのは、コードから直接明らかではないものです。つまり、根底にある意図、仮定、影響、制限などです。

コードがXを実行していることを一目で判別できることは、コードがYを実行していないことを判別できるよりもはるかに簡単です。彼はYを文書化する必要があります...

たとえば、見栄えがよく、明白であるが実際には入力のすべてのベースをカバーしていないコードの例を彼に見せて、それが見つかったかどうかを確認することができます。

自己文書化されたコードは、コメントの代わりになるものだと思います。コードがどのようにまたはなぜそうであるかを説明するためにコメントが必要な場合は、より説明的になるように変更する必要がある関数または変数の名前があります。コメントで不足分を補うのか、一部の変数と関数の名前を変更してコードをリファクタリングするのかは、コーダーの責任です。

ただし、ドキュメントはシステムの使い方ではなく、システムの使用方法を説明するために他の人に提供するものであるため、実際にドキュメントを置き換えることはできません。

編集：私（およびおそらく他のすべての人）は、おそらくデジタル信号処理（DSP）アプリに非常によくコメントする必要があるという規定を持っているはずです。これは主に、DSPアプリが基本的に値の配列が供給される2つのforループであり、値を追加/乗算/ etc ...するためです。プログラムを変更するには、配列の1つで値を変更します...あなたはその場合にやっています;）

数学のコードを書くとき、私は時々、エッセイのような長いコメントを書いて、数学、コードが使用する表記規則、およびそれらすべてがどのように適合するかを説明することが役立つことに気づきました。ここでは何百行ものドキュメントについて話している。

私はできる限り自己文書化するようにコードを作ろうとしていますが、数か月後にコードに取り掛かるときは、ハッシュを作成しないように説明を読む必要があります。

もちろん、ほとんどの場合、このような極端な方法は必要ありません。この話の教訓は次のとおりです。コードが異なれば、必要なドキュメントの量も異なります。コメントを必要としないほど明確に記述できるコードもあります。そのため、明確に記述し、そこでコメントを使用しないでください。

ただし、多くのコードには意味のあるコメントが必要なので、できるだけ明確に記述し、必要なだけコメントを使用してください...

私は、多くの人がそうであるように、真に自己文書化するためには、コードが何らかの形の意図を示す必要があると主張します。しかし、誰もまだBDDについて言及していないことに驚いています-Behavior- Driven Development。アイデアの一部は、コードの目的を説明する自動テスト（コード）があることです。これは、他の方法では明らかにすることが非常に困難です。

適切なドメインモデリング 
+良い名前（変数、メソッド、クラス） 
+コード例（ユースケースの単体テスト） 
=自己文書化ソフトウェア 

コードに加えて追加のコメントが明確になるいくつかの理由：

• あなたが見ているコードは自動的に生成されたので、次にプロジェクトがコンパイルされたときにコードへの編集はすべて破壊される可能性があります
• 単純ではない実装は、パフォーマンスの向上（ループの展開、高価な計算用のルックアップテーブルの作成など）とトレードオフされました。

そのすべては、チームがドキュメントで評価するものにあります。なぜ/意図ではなく方法/理由を文書化することが重要であり、これは常に自己文書化コードに取り込まれるわけではありません。get / set noこれらは明白です-しかし、計算、検索などの理由を表現する必要があります。

国籍が異なる場合は、チームの違いにも注意してください。辞書の違いは、メソッドの命名に大きく影響します。

BisectionSearch

BinarySearch

BinaryChop

3つの異なる大陸で訓練を受けた開発者から提供されたこれらの3つの方法は、同じことを行います。アルゴリズムを説明するコメントを読むことによってのみ、ライブラリの重複を特定できました。

私にとって、コメントが必要なコードを読むのは、知らない言語でテキストを読むようなものです。声明を見るが、それが何をするのか、なぜなのか理解していない。フレーズを読んで、その意味を理解するために辞書を調べる必要があります。

通常、それが何をするかを自己文書化するコードを書くのは簡単です。なぜそうなるのかを説明するには、コメントの方が適していますが、ここでもコードの方が優れている場合があります。抽象化のあらゆるレベルでシステムを理解している場合は、次のようにコードを整理してみてください

public Result whatYouWantToDo(){
  howYouDoItStep1();
  howYouDoItStep2();
  return resultOfWhatYouHavDone;
}

メソッド名は意図を反映し、メソッド本体は目標の達成方法を説明します。いずれにしても、タイトル全体で本全体を伝えることはできません。そのため、システムの主な抽象化、さらには複雑なアルゴリズム、重要なメソッドコントラクトやアーティファクトを文書化する必要があります。

あなたの同僚が作成したコードが本当に自己文書化されている場合-あなたと彼の幸運。同僚のコードにコメントが必要だと思われる場合-コメントが必要です。その中で最も重要な場所を開き、一度読んで、すべてを理解したかどうかを確認してください。コードが自己文書化されている場合-必要があります。そうでない場合-同僚から回答を受け取った後、同僚に質問して、その回答がコメントまたはコードに事前に文書化されていなかった理由を尋ねます。彼はコードが彼のような賢い人のための自己文書であると主張することができますが、彼はとにかく他のチームメンバーを尊重する必要がありますコメント。

ほとんどのドキュメント/コメントは、将来のコードエンハンサー/開発者を支援するために役立ち、コードを保守可能にします。多くの場合、新しい機能を追加したり最適化したりするために、後でモジュールに戻ることになります。その時点では、コメントを読むだけでコードを理解する方が、多数のブレークポイントをたどるより簡単です。その上、既存のものを解読するよりも、新しいロジックを考えることに時間を費やしたいのです。

彼が得ているかもしれないことは、コメントがコードが何をしているかを説明する場合、それが何であるかを明確にするために書き直されるべきであるということです。それは彼が自己文書化コードによって意味するものです。多くの場合、これは、長い関数を説明的な関数名で論理的に小さな断片に分割することを意味します。

これは、コードにコメントを付けるべきではないという意味ではありません。これは、コメントがコードがそのように書かれている理由を提供する必要があることを意味します。

コードを読みやすくするため、常に自己文書化コードを実現するように努めるべきだと思います。しかし、あなたはまた、物事について実用的でなければなりません。

たとえば、通常はすべてのクラスメンバーにコメントを追加します（これにはドキュメントコメントを使用します）。これは、メンバーが何をすべきかを説明しますが、それをどのように実行するかではありません。コード（特に古いコード）を読んでいると、メンバーの目的をすばやく思い出すことができ、コードのフローがかなり飛び跳ねている場合は特に、コードを読んで解決するよりも簡単であることがわかります。

これは私の意見です。私はコメントなしで働く人々をたくさん知っています、そして彼らはこれが問題ではないと思うと言います。しかし、私は誰かに、彼らが6か月前に書いた方法について尋ねました。メソッドがコメント化されている場合、これは問題ではありません。

最後に、コメントはコードと同じようにシステムの一部であることを覚えておく必要があります。機能をリファクタリングおよび変更するときは、コメントも更新する必要があります。コメントが正しくない場合、コメントは役に立たないよりも悪いため、コメントを使用することに対するこれは1つの議論です。