documentation - 自己文書化コードとは何ですか?十分に文書化されたコードを置き換えることができますか?

Question

自分のコードにはコメントは必要ないと主張する同僚がいます。それは「自己文書化」です。

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

彼の見解を理解するのを手伝ってください。

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

多分それは私自身の制限に過ぎませんが、それがどのように良い習慣になるかわかりません。

これは議論を意図したものではありません - 十分にコメントされ、文書化されたコードが優先される理由を持ち出さないでください - これを示す多くのリソースがありますが、私の仲間には説得力がありません. そうではないと彼を納得させるには、彼の視点をもっと完全に理解する必要があると思います。必要に応じて新しい質問を開始しますが、ここで議論しないでください。

また、自己文書化コードに反対している人たち - これは主に、自己文書化コードの伝道者の視点 (つまり、肯定的な側面) を理解するのに役立つためです。

score 403 · Accepted Answer

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

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 番目の例の方がいつでも好きです。おそらく、あなたの友人が自己文書化されたコードと言うとき、それについて話しているのでしょう。

それはあなたがしていることの文脈に依存すると思います。この場合、自己文書化されたコードでおそらく十分ですが、背後で行われていることの背後にある方法論 (この例では方程式) を詳述するコメントも役立ちます。

score 182 · Accepted Answer

私の意見では、どのコードも自己文書化する必要があります。優れた自己文書化されたコードでは、すべての識別子 (変数、メソッド、クラス) に明確な意味名があるため、すべての行を説明する必要はありません。必要以上のコメントがあると、実際にはコードを読むのが難しくなります (!)。

すべてのクラス、メンバー、型、およびメソッドのドキュメントコメント (Doxygen、JavaDoc、XML コメントなど) を書き込みます。
自己文書化されていないコードの部分を明確にコメントし、かつ
意図を説明するコードブロックごとにコメントを書き込む、またはより高い抽象化レベルでコードが行うこと (つまり、ディレクトリ内のすべてのファイルをループする代わりに、10 MB を超えるすべてのファイルを検索し、ファイルサイズが 10 を超えるかどうかをテストします) MB、true の場合は利回りを返します)

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

score 173 · Accepted Answer

コード自体は、コードが何をするかについて常に最新の説明になりますが、私の意見では、コメントの最も重要な側面である意図を説明するのは非常に困難です。それが適切に書かれていれば、コードが何をするかはすでにわかっています。

score 99 · Accepted Answer

かつて誰かが言った

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

score 39 · Accepted Answer

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

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

score 19 · Accepted Answer

コードの特定の行が自己文書化されているかどうかを疑問視することは適切だと思いますが、結局のところ、コードのスライスの構造と機能を理解していない場合、ほとんどの場合、コメントは役に立ちません。たとえば、「正しくコメントされた」コードの 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);

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

score 17 · Accepted Answer

これをどこから入手したか忘れましたが、次のとおりです。

プログラム内のすべてのコメントは、読者への謝罪のようなものです。「私のコードが不透明すぎて、見ただけでは理解できないことをお詫び申し上げます」. 私たちは完璧ではないことを受け入れる必要がありますが、完璧になるように努力し、必要なときに謝罪し続けます.

score 14 · Accepted Answer

自己文書化コードは "DRY" (Don't Repeat Yourself) の良い例です。コード自体に含まれる、または含まれる可能性があるコメント内の情報を複製しないでください。

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

コードの短いスニペットが何をするかを説明するのではなく、それをメソッドに抽出し、わかりやすい名前を付けます (コメントテキストの短縮バージョンなど)。

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

等。

この後、コード内で情報を繰り返すだけのコメントは削除する必要があります。

これは、コメントがまったくないという意味ではありません。意図に関する情報 (「理由」) など、コードに入力できない情報がいくつかあります。理想的なケースでは、コードとコメントが互いに補完し合い、互いに情報を複製することなく、それぞれが独自の説明値を追加します。

score 14 · Accepted Answer

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

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

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)

さて、この「情報に通じた読者」という考え方は、非常に主観的で状況に左右されます。あなたや他の誰かがあなたの同僚のコードをたどるのに苦労しているなら、彼は知識のある読者という彼の考えを再評価するのがよいでしょう。コードの自己文書化を呼び出すには、使用されている言語とライブラリにある程度精通している必要があります。

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

score 13 · Accepted Answer

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

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

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

score 9 · Accepted Answer

順番に：

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

ただし、真に自己文書化されたコードには、多くの自己規律とチーム規律が必要であることに注意することが重要です。もっと宣言的にプログラミングすることを学ばなければならず、非常に謙虚になり、「賢い」コードを避ける必要があります。

score 7 · Accepted Answer

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

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

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

ほんのひとつまみの塩...

score 6 · Accepted Answer

たとえば、次のスニペットを検討してください。

/**
 * 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;
 }

それでも、些細なコードの場合は、コメントを付けないほうが好みです。意図と全体的な構成は、コードの外側にある別のドキュメントでよりよく説明されています。

score 5 · Accepted Answer

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

score 5 · Accepted Answer

TeX の Donald E. Knuth によって 1981 年に開発された手法であり、「The Art of Computer Programming」で有名な「 Literate Programming 」を誰ももたらしていないことに驚いています。

前提は単純です。コードは人間が理解する必要があり、コメントはコンパイラによって単に破棄されるため、プログラミング言語の要件にとらわれない、コードの意図を完全にテキストで説明した、必要なものをすべての人に提供しないでください。、人間の読者用、およびコンパイラー用の純粋なコード。

リテレートプログラミングツールは、どの部分がソースで、何がテキストであるかをツールに伝えるドキュメントの特別なマークアップを提供することでこれを行います。プログラムは後でソースコード部分をドキュメントから切り取り、コードファイルを組み立てます。

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

図書館でクヌースの本を見つけることができれば (Donald E. Knuth, Literate Programming, Stanford, California: Center for the Study of Language and Information, 1992, CSLI Lecture Notes, no. 27.) 読むべきです。

これは自己文書化コードであり、理由などをすべて備えています。素敵なドキュメントにもなりますが、それ以外はすべてよく書かれたコメントです:-)

score 4 · Accepted Answer

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

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

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

あなたはあなたが書いたものを読むことができるべきですか？

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

ソースコードにあいまいさを持たせることはできません。そのため、テキストよりも多くの構造を組み込む必要があります。テキストはコンテキストでのみ機能します。コンテキストは、テキストを使用するときに当然のことと見なされます。ソースコードのコンテキストは常に明示的です。C＃で「使用する」と考えてください。

ほとんどのプログラミング言語には冗長性があるため、一貫性がない場合でもコンパイラーが私たちを捕まえることができます。他の言語はより多くの推論を使用し、その冗長性を排除しようとします。

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

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

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

score 4 · Accepted Answer

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

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

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

score 3 · Accepted Answer

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

とはいえ、ドキュメンテーションは、システムがどのように機能するかというよりも、システムの使用方法を説明するために他の人に提供するものであるため、実際にはドキュメンテーションに取って代わることはできません。

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

score 3 · Accepted Answer

自己文書化コードは、時間の経過とともにコード、コメント、および文書化が分岐するという問題から簡単にオプトアウトできます。そして、明確なコードを書くことは規律の要素です (自分自身にそれほど厳格な場合)。

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

コードは、できるだけ読みやすく明確にする必要があります。
コメントは、私が行った設計上の決定の理由を示す必要があります。たとえば、なぜこのアルゴリズムを使用するのか、またはコードの制限など: 次の場合は機能しません ... (これはコード内の契約/アサーションで処理する必要があります) (通常は関数/手順内)。
ドキュメントには、使用法 (変換の呼び出し)、副作用、可能な戻り値を記載する必要があります。jDoc や xmlDoc などのツールを使用してコードから抽出できます。したがって、通常は関数/手順の外にありますが、記述されているコードに近いです。

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

score 3 · Accepted Answer

いわゆる自己文書化コードの本当の問題は、それが実際に何をするかを伝えることです。いくつかのコメントは誰かがコードをよりよく理解するのに役立つかもしれませんが (例えば、アルゴリズムの手順など)、それはある程度冗長であり、あなたが同僚を納得させるとは思えません。

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

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

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

score 3 · Accepted Answer

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

私は自分のコードを可能な限り自己文書化するように努めていますが、数か月後に作業に戻ったときに、説明を読んでハッシュを作成しないようにする必要があります。

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

しかし、多くのコードは意味を理解するためにコメントを必要とするため、できるだけ明確に記述してから、必要なだけ多くのコメントを使用してください...

score 3 · Accepted Answer

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

優れたドメイン モデリング
+ 適切な名前 (変数、メソッド、クラス)
+ コード例 (ユースケースからの単体テスト)
= 自己文書化ソフトウェア

score 2 · Accepted Answer

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

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

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

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

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

score 2 · Accepted Answer

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

score 2 · Accepted Answer

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

表示されているコードは自動的に生成されたものであるため、次回プロジェクトをコンパイルしたときに、コードを編集すると上書きされる可能性があります。
単純ではない実装は、パフォーマンスの向上と引き換えに行われました (ループのアンロール、高価な計算のためのルックアップテーブルの作成など)。

score 2 · Accepted Answer

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

また、国籍が異なる場合は、チームの違いにも注意してください。言葉遣いの違いは、メソッドの命名に影響を与える可能性があります。

二分検索

バイナリサーチ

バイナリチョップ

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

score 1 · Accepted Answer

純粋に自己文書化されたコードが達成可能であるかどうかに関係なく、とにかくやるべきことが頭に浮かぶことがいくつかあります。

「驚くべき」コードは絶対に使用しないでください。つまり。物事を再定義するために愚かなマクロを使用しないでください。演算子のオーバーロードを誤用しないでください。これを賢くしようとしないでください。
適切なポイントでコードを分割します。適切な抽象化を使用してください。ローリングバッファー（固定長のバッファーで、一方の端でアイテムが追加され、もう一方の端でアイテムが削除される2つのポインター）をインライン化する代わりに、適切な名前の抽象化を使用します。
関数の複雑さを低く抑えます。長すぎたり複雑になったりする場合は、他の機能に分割してみてください。

特定の複雑なアルゴリズムを実装する場合は、アルゴリズムを説明するドキュメント（またはへのリンク）を追加します。ただし、この場合、間違いを犯しやすいため、不要な複雑さを取り除き、読みやすさを向上させるために、さらに注意を払うようにしてください。

score 1 · Accepted Answer

コメントなしでコードが完全に明確でない場合は、コードを改善する余地があります。

「不明瞭なコードにコメントしないでください」と言っているのではありません。私は「あなたのコードを明確にする」と言っています。

何らかの方法でコードを不明確なままにしてしまう場合は、コメントを使用して補正してください。

score 1 · Accepted Answer

優れた設計構造は、「この関数は一般的です」というコメントがなくても、一般的な使用のための関数とランダムなビジネスロジックのための関数があることを指摘するのに役立ちます。

ただし、設計と仕様のドキュメントを忘れてはなりません。それらには、コメントで必ずしも必要ではないテキストの多くが含まれているか、少なくとも含まれている必要があります。多くの場合、ソフトウェアにはユーザーマニュアルやその他の説明文書も含まれており、それらはプログラムの機能と同期している必要があります。ユーザーがソフトウェアの機能をマニュアルではなくソースコードから調べなければならない場合、状況は良くありません。したがって、自己文書化コードは、実際のソフトウェアが文書化されていることを意味しません。

機能のトレーサビリティについても考えてください。マニュアルがあれば、保守性を高めるために、機能をソースコードまでたどり、遡ることができるはずです。マニュアルや仕様書はプログラミングに関するものではなく、ソフトウェアエンジニアリングに関するものです。ソフトウェアが大きくなればなるほど、より多くのエンジニアリングが必要になります。

score 1 · Accepted Answer

自己文書化コードは、簡単に理解できるコードです。変数の命名は、コードを自己文書化するのに大いに役立ちますが、最善の戦術は、複雑なロジックを小さなチャンクに分割し、その情報を冗長で有益な名前を持つ個別のメソッドにリファクタリングすることだと思います。そうすれば、複雑なメソッドは単純に実行するステップのリストになります。小さなプライベートヘルパーメソッドは、独自のメソッド名で十分に文書化され、複雑なメソッドは、実行される一連の抽象的なステップとして文書化されます。実際には、この戦略を常に完全に適用できるとは限らないため、コメントは依然として非常に役立ちます。さらに、理解しやすいコードを書くのに役立つツールを完全に放棄するべきではありません。

score 1 · Accepted Answer

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

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

score 1 · Accepted Answer

コードを読みやすくするため、自己文書化コードを実現するよう常に努力する必要があると私は信じています。ただし、物事については実用的である必要もあります。

たとえば、私は通常、すべてのクラスメンバーにコメントを追加します (これにはドキュメントコメントを使用します)。これは、メンバーが何をすべきかを説明しますが、どのように行うかは説明しません。コード、特に古いコードを読んでいるときに、メンバーの目的をすばやく思い出すのに役立ちます。また、特にコードの流れがかなりジャンプする場合は、コードを読んでそれを解決するよりも簡単だと思います。 .

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

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

score 1 · Accepted Answer

すべてかゼロかではなく、適切な量のドキュメントの問題だと思います。関数のパラメーターに適切な名前が付けられている場合、多くの場合、それらが何であるかを正確に言う必要はありません。たとえば、char *CustomerName はかなり明白です。パラメータに assert 値の範囲を使用する場合、それらの範囲も文書化する必要はありません。IMO、ドキュメントは、明白ではないため説明が必要なすべてをカバーする必要があり、ほとんどのコードにはドキュメントが必要です。個人的には、ほとんどの場合、説明的なドキュメントよりも、特定の関数がどのように機能するかを説明する例を見たいと思っています。

ドキュメンテーションのためのドキュメンテーションは時間の無駄になる可能性があります。ドキュメンテーションはコードベースを最新の状態に保つためにメンテナンスが必要だからです。誰もそれを読んでも利益を得られない場合は、作成しないでください。

score 1 · Accepted Answer

私はこれを好転させます。

彼のコードで理解できないことを自問し、それを文書化するように依頼してください。そして、あなたも私たちに教えてくれるかもしれません。

score 1 · Accepted Answer

これがあなたの質問に対する私の最良の答えです。

自己文書化コードは、クラス、メソッド、関数、および変数名を使用して明確に記述されたコードで、その意図と機能を簡単に理解できるようにします。うまくいけば、それはドキュメントです。

十分にコメントされ、文書化されているコードを置き換えることができますが、私はめったに見たことがありません。多くの場合、プログラマーはこれを行うのに十分な能力があると信じていますが、プログラマーをノックダウンする最善の方法は、質問を開始することです。あまりにも多くの説明を開始する必要がある場合は、コードが十分に明確ではありませんでした。それが何をするかを知るためにコードを読む必要はありません。

その方が良い場合もあるでしょう。コードが小さくて単純な場合は、ドキュメントを追加して混乱させることができます。

アルゴリズムを含むコードには、コメントを含める必要があります。ほとんどの場合、元のプログラマでさえ、数か月前に長い関数を書いたときに何を考えていたかを思い出せません。

score 1 · Accepted Answer

これは素晴らしい質問です。コメントを許可した最初のプログラミング言語にさかのぼります。コードは、可能な限り自己文書化する必要があります。明らかなことを指摘するコメントは削除する必要があります。特定のメソッドまたはコードのセクションの意図、目的、および使用法を理解しやすくするコメントは、問題の言語またはコードにあまり慣れていない可能性のある私たちにとって非常に貴重です。API ドキュメントの生成を可能にする構造化されたコメントが良い例です。チェックボックスがチェックされているかどうかを確認する IF ステートメントにコメントしないでください。コメントで明白なことを言い直すことは、私たちの宇宙で最悪の無駄なキーストロークです.

//For example, the above text deals with what is a useful comment

score 1 · Accepted Answer

私はかつて、金融スイートを大企業に売り込もうとしている男性と仕事をしたことがあります。彼らは、彼が 30 ページ以上のアセンブラールーチンを作成したソースコードを文書化するよう主張し、「文書化されている、見てください」と言いました。優れた製品、優れた実装者、しかし...

とにかく、私の考えでは、上記の重要なコメントはコンテキストを設定することです。このスニペットは、自己文書化されていると述べられています。

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

しかし、私はそれを完全に理解するためにコンテキストが必要です。

score 1 · Accepted Answer

コメントしていないキャンプからのいくつかの視点。

「よくコメントされた」(冗長な) コードは、読みにくく、理解しにくいものです。まず、スキャンするテキストが増えるだけです。これにより、CodeBase を理解するための認知作業が増加します。機能しないテキストが、コードを表示するために使用できる画面スペースを占有します。

コメントのもう 1 つの大きな問題は、信頼性が低いことです。特に古いコードベースでは、コメントの腐敗はビットの腐敗よりも速く設定されます。

そしてもちろん、コメントを書く努力も必要です。時折1行の明確化を除いて、コードにコメントを付け始めるたびに、2つの罪悪感のいずれかを感じます

この情報は、サポートドキュメント全体に記載する必要があります
コードをクリーンアップする必要がある

score 1 · Accepted Answer

自己文書化コードはばかげています。数週間、数か月、または数年後にコードを再確認しなければならなかった人なら誰でも、それを知っています (私の場合は数日)。（もしかしたら、このアイデアを推し進めている人は、まだ耳の後ろが濡れているのかもしれません!?!?!)

意味のあるわかりやすいデータ名を使用し、コードを賢く分解し、なぜ自分がしたことをしたのかについてのヒントを自分自身に残してください。そうすれば、より豊かで充実した人生を送ることができます。

とはいえ...かつてビル・ゲイツに帰せられた「コードはドキュメントです」という引用を読みました。

図に行きます。

score 1 · Accepted Answer

ここでは非常に混合された入力のようです:)

新しい開発には疑似コードプログラミングプロセスを使用します。これにより、実質的にコードが自己文書化されます。私は新しいコードを書くときだけ疑似コードを書き始め、それを拡張します。これがベストプラクティスだと言っているわけではありません。サードパーティやレビュアーなどに渡す場合、コードのドキュメントがたくさん必要であることがわかっている場合に役立つと思われる1つの手法を強調しているだけです...それもコードの行を書く前に、問題を強調することがあります。

' check database is available
  ' if it is then allow the procedure
  ' if it isnt roll back and tidy up 
' move onto something else

になります;

' check database is available
  if checkDBStateResult(currentDB) = Open then 
     ' if it is then allow the procedure
          proc.Ok = True 
  else
     ' if it isnt roll back
          proc.Ok = False
          CleanUp()
  end if

score 1 · Accepted Answer

コメントは意図を捉えるべきだと指摘されてきましたが、私はもう少し先に進みたいと思います。

どのクラスの問題にも、それを説明するための理想的な (またはそれに近い) 語彙と構文があり、そのような問題を抱えている人にそれらを説明するように頼むだけでそれがわかると思います (その人が明確に考えることができると仮定して) .

その語彙と構文が (クラス、メソッドなどを定義することによって) コンピューター言語のコードに簡単にマップされる場合、そのコードは自己文書化できます。また、ドメイン固有言語である IMO が作成されました。(そして、それが私の「宣言的」の大まかな定義です。)

この理想に失敗して、問題がコンピューターコードに直接マッピングされない場合は、2 つを結び付ける何かが必要になります。IMO、それがコメントの目的です。

そうすれば、問題が変化したときに、コードの対応する部分を見つけて変更することができます。

編集：ちなみに、私は、すべての名詞がクラスになり、すべての動詞がメソッドになるOOP方法論を支持しているわけではありません。そのように構築されたブロートウェアを十分に見てきました。

score 0 · Accepted Answer

自己文書化されたコードは、コメントが不要なほど明確なコードです。小さな例を挙げます：

//iterate from 0 to 100
for(int i=0; i < 100; i++) {
   println i
}

コードは明確なので、コメントはほとんど役に立ちません。文書化は良い方法ですが、追加の文書化はコードに不必要なノイズを追加する可能性があります。あなたの同僚が知っておく必要があるのは、誰もが他人のコードを読んでその詳細をすべて認識できるわけではないということです。

int calc(int a, int b) {
   return sqrt(a*a + b*b); //pythagoras theorem
}

最後のスニペットは、コメントなしでは解読が非常に困難です。もっと工夫された他の例を想像することができます。

documentation - 自己文書化コードとは何ですか?十分に文書化されたコードを置き換えることができますか?

44 に答える 44

Related

Reference