自己文書化コードとは何ですか？よく文書化されたコードを置き換えることができますか？
自分のコードにはコメントは不要で、「自己文書化」だと主張する同僚がいます。
私は彼のコードをレビューしましたが、他の人が作成したコードよりも明確ですが、自己文書化されたコードがコメント付きで文書化されたコードと同様に完全で有用であることにはまだ同意しません。
his視点を理解してください。
- 自己文書化コードとは
- よくコメントされ文書化されたコードを本当に置き換えることができますか
- よく文書化されコメントされたコードよりも優れている状況はありますか
- コメントなしでコードを自己文書化できない例はありますか
たぶんそれは私自身の制限だけかもしれませんが、それがどのように良い習慣になるかわかりません。
これは議論を意味するものではありません-よくコメントされ文書化されたコードが優先される理由を持ち出さないでください-これを示す多くのリソースがありますが、彼らは私の仲間を納得させません。そうでなければ、彼を説得するために彼の視点をより完全に理解する必要があると思います。必要に応じて新しい質問を開始しますが、ここで議論しないでください。
すごい迅速な対応！回答がここの他のすべての回答と大幅に異なる場合を除き、新しい回答を追加するのではなく、既存の回答をすべて読んで回答にコメントを入力してください。
また、自己文書化コードに反対している皆さん-これは主に、自己文書化コードの伝道者の観点（肯定的な側面）を理解するのに役立ちます。あなたが話題にとどまらない場合、他の人があなたに投票することを期待しています。
私の意見では、どのコードも自己文書化する必要があります。自己文書化された適切なコードでは、すべての識別子（変数、メソッド、クラス）に明確なセマンティックがあるため、すべての行を説明する必要はありません名前。必要以上のコメントがあると、実際にはコードを読むのが難しくなります（！）。
- すべてのクラス、メンバー、タイプ、およびメソッドのドキュメントコメント（Doxygen、JavaDoc、XMLコメントなど）を書き込みます。
- not自己文書化であるコードの部分を明確にコメントする
- 意図を説明するコードブロックごとにコメントを書き込みます。または、コードがより高い抽象化レベルで行うこと（つまり10 MBを超えるすべてのファイルを検索します）ディレクトリ内のすべてのファイルをループする代わりに、ファイルサイズが10 MBより大きいかどうかをテストし、trueの場合にreturnを返します）
私の意見では、彼のコードとドキュメントは問題ありません。自己文書化されたコードはnotを意味することに注意してください。コメントはないはずですが、不必要なコメントはありません。ただし、コード（コメントやドキュメンテーションコメントを含む）を読むことで、コードの機能と理由をすぐに理解できるはずです。 「自己文書化」コードがコメント付きコードよりも理解に時間がかかる場合、それは実際には自己文書化ではありません。
これはコメントとコードに関するものなので、実際のコードを見てみましょう。この典型的なコードを比較してください：
float a, b, c; a=9.81; b=5; c= .5*a*(b^2);
whatが実行されていることを示すこの自己文書化コードに対して：
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番目の例を好むでしょう。そしておそらくあなたの友人が自己文書化されたコードを言うとき、それはあなたの話していることでしょう。
私はそれがあなたがしていることの文脈に依存していると言うでしょう。私にとっては、この場合、おそらく自己文書化されたコードで十分ですが、背後にあることの背後にある方法論（この例では、方程式）を詳述するコメントも有用です。
コード自体は、常にコードの機能に関する最新の説明になりますが、私の意見では、intentを説明することは非常に困難です。これは最も重要な側面ですコメントの。適切に記述されていれば、コードがwhatを知っているので、why on earthを知っている必要があります！
誰かが一度言った
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);
私自身の個人的な経験では、コメントが絶対に必要な「通常の」コーディング状況はほとんどありません。たとえば、どのくらいの頻度で独自のアルゴリズムをローリングしますか？基本的に他のすべては、コーダーが使用中の構造と、それらの特定の構造を使用するためにシステムを動かした選択を理解できるように、システムを構造化することの問題です。
私はこれをどこから入手したか忘れますが、：
プログラム内のすべてのコメントは、読者にとって謝罪のようなものです。 「コードが非常に不透明なので、見ただけでは理解できません。」私たちは自分が完璧ではないことを受け入れなければなりませんが、完璧になるよう努力し、必要なときに謝罪を正しくします。
自己文書化コードは、「DRY」（自分自身を繰り返さない）の良い例です。コード自体に含まれる、または含まれる可能性のあるコメントの情報を複製しないでください。
変数の用途を説明するのではなく、変数の名前を変更します。
コードの短い断片が何をするのかを説明するのではなく、メソッドに抽出して説明的な名前（おそらく、コメントテキストの短縮版）を付けます。
複雑なテストが何をするのかを説明するのではなく、それをメソッドに抽出し、適切な名前を付けます。
等。
この後、それほど多くの説明を必要としないコードになり、それ自体を説明するので、コード内の情報を単に繰り返すコメントを削除する必要があります。
これは、まったくコメントがないという意味ではなく、意図に関する情報（「理由」）など、コードに入れることができない情報がいくつかあります。理想的な場合、コードとコメントは互いに補完し、それぞれが他の情報を複製することなく一意の説明値を追加します。
自己文書化コードは良い習慣であり、適切に行われれば、あまり多くのコメントを読むことなくコードの意味を簡単に伝えることができます。特に、チームの全員がドメインをよく理解している状況では。
とはいえ、コメントは新規参入者やテスター、ドキュメント/ヘルプファイルの生成に非常に役立ちます。
自己文書化コード+必要なコメントは、チーム全体の人々を支援するのに大いに役立ちます。
まず、同僚のコードが実際にあなたが見た他のコードよりも明確であると聞いてうれしいです。それは、彼がコードをコメントするのが面倒だという言い訳として、おそらく「自己文書化」を使用していないことを意味します。
自己文書化コードは、知識のある読者が何をしているのかを理解するためにフリーテキストのコメントを必要としないコードです。たとえば、次のコードは自己文書化されています。
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)
さて、この「知識のある読者」という考え方は、非常に主観的かつ状況的です。あなたや他の誰かがあなたの同僚のコードを追跡するのに苦労しているなら、彼は知識のある読者の彼の考えを再評価するためにうまくいくでしょう。コードの自己文書化を呼び出すには、使用する言語とライブラリにある程度精通している必要があります。
「自己文書化コード」を書くために私が見た最も良い議論は、それが書かれているようにコードに同意しないフリーテキストの注釈の問題を避けるということです。最も批判的なのは、コードはwhatおよびhowを記述できますが、それ自体はwhyが特定の方法で行われていることを説明できないことです。 。
順番に：
- 自己文書化コードは、その意図を読者に明確に表現するコードです。
- 完全ではありません。コメントは、why特定の戦略が選択された場合のコメントに常に役立ちます。ただし、whatのコードのセクションが説明しているコメントは、自己文書化が不十分であり、リファクタリングを使用できるコードを示しています。
- コメントは嘘をつき、時代遅れになります。コード
いつも言う本当のことを言う可能性が高いです。 - コメントなしではコードのwhatを十分に明確にできないケースを見たことはありません。ただし、前に言ったように、whyについてのコメントを含める必要がある場合があります。
ただし、真に自己文書化するコードには多くの自己規律とチーム規律が必要であることに注意することが重要です。もっと宣言的にプログラムすることを学ばなければならず、非常に謙虚で、誰でも書けるような非常に明白なコードを好む「賢い」コードを避ける必要があります。
まず、次のスニペットを検討してください。
/**
* 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;
}
それでも、些細なコードの場合はコメントを付けたくないのです。意図と全体的な組織は、コードの外部の別のドキュメントでより適切に説明されています。
「自己文書化コード」を読むと、それが何をしているのかがわかりますが、なぜその特定の方法でそれが行われているのかを常に推測することはできません。
ビジネスロジック、セキュリティ、ユーザーの要求など、プログラミング以外の制約が多数あります。
メンテナンスを行うとき、これらのバックゴーランド情報は非常に重要になります。
ほんの少しの塩...
違いは「何」と「方法」の違いです。
- ルーチンが何を行うかを文書化する必要があります。
- 特別な場合を除いて、「どのように」それを行うかを文書化するべきではありません（例えば、特定のアルゴリズム論文を参照してください）。自己文書化する必要があります。
ドナルド・クヌースの Literate Programming コンセプトを実装するための「WEB」プロジェクトについて聞いたことがありますか？自己文書化コード以上のものです。コードとしてコンパイルして実行できるドキュメントに似ています。しかし、今日どの程度使用されているのかわかりません。
私が働いていた会社では、プログラマーの1人がモニターの上部に次のものを貼り付けていました。
「コードを維持する人が、あなたが住んでいる場所を知っている殺人マニアのようにコードを文書化してください。」
同僚に指摘したいことの1つは、自分のコードをどのように自己文書化しても、他の代替アプローチが考慮され、破棄された場合、その情報でコードをコメントしない限り、その情報は失われます。代替案が検討されたこと、そしてなぜそれが反対されたのか、そしてコードコメントが時間をかけて存続する可能性が最も高いことを知ることも同じくらい重要です。
1981年にTeXのドナルドE.クヌースと「コンピュータプログラミングの芸術」の名声によって開発されたテクニックである「 Literate Programming 」をもたらした人がいないことに驚いています。
前提は単純です。コードは人間が理解する必要があり、コメントはコンパイラーによって単に破棄されるため、誰もが必要なものを提供しないようにしましょう-プログラミング言語の要件に縛られないコードの意図の完全なテキスト記述、人間の読者およびコンパイラーの純粋なコード用。
Literate Programmingツールは、ドキュメントに特別なマークアップを与えることでこれを行い、ツールにどの部分をソースとするか、テキストとは何かを伝えます。このプログラムは、後でソースコード部分をドキュメントから取り出し、コードファイルを組み立てます。
Webで例を見つけました： http://moonflare.com/code/select/select.nw またはHTMLバージョン http://moonflare.com/code/ select/select.html
ライブラリに関するクヌースの本を見つけることができる場合（ドナルドE.クヌース、Literate Programming、スタンフォード、カリフォルニア：言語と情報の研究センター、1992、CSLIレクチャーノート、第27号）をお読みください。
それは自己文書化コードで、推論とすべてを完備しています。素敵なドキュメントを作成することもできますが、それ以外はすべてよく書かれたコメントです:-)
コードが自己文書化されているという観点から、私は夢中になります。特定のコード行またはサブアルゴリズムは実際に自己文書化されている場合がありますが、より大きな写真での目的は単にそうではありません。
私はこれにとても不満を感じました。1、2か月前、私は自分の視点を説明するブログ記事全体を書きました。 ここに投稿 。
私の見解はこの投稿に書かれています：
抜粋：
プログラムの微妙な振る舞いを説明するために多くのコメントを書く代わりに、ロジックが自明になるように再構築してみませんか？メソッドの実行内容を文書化する代わりに、そのメソッドの明確な名前を選択してみませんか？未完成の作業を示すためにコードにタグを付ける代わりに、単にNotImplementedException（）をスローしないのはなぜですか？コメントが上司、同僚、またはコードを読んでいる人に丁寧に聞こえるかどうか心配するのではなく、コメントをまったく書かないことで心配しないでください。
コードが明確であればあるほど、コードの保守、拡張、将来のエディションでの作業が容易になります。コードの見栄えが悪いほど、コメントする必要が少なくなります。コメントが多いほど、メンテナンスコストが高くなります。
多くの有効な答えにもう一つの視点を提供したいと思います：
ソースコードとは何ですか？プログラミング言語とは何ですか？
マシンはソースコードを必要としません。彼らはアセンブリの実行を喜んでいます。プログラミング言語は私たちの利益のためです。 Assemblyを書きたくありません。何を書いているのかを理解する必要があります。プログラミングとは、コードを書くことです。
あなたが書いたものを読むことができるべきですか？
ソースコードは人間の言語で書かれていません。試されました（たとえばFORTRAN）が、完全に成功しているわけではありません。
ソースコードにあいまいさはありません。そのため、テキストよりも多くの構造を配置する必要があります。テキストはコンテキストでのみ機能し、テキストを使用する場合は当然のことと考えています。ソースコードのコンテキストは常に明示的です。 C＃で「使用する」と考えてください。
ほとんどのプログラミング言語は冗長性を備えているため、一貫性が保てないときにコンパイラーが私たちを捕まえることができます。他の言語はより多くの推論を使用し、その冗長性を排除しようとします。
型名、メソッド名、変数名はコンピューターに必要ありません。これらは参照のために使用されます。コンパイラはセマンティクスを理解していません。それは私たちが使用するものです。
プログラミング言語は、人間と機械の間の言語的橋渡しです。それは私たちにとって書き込み可能であり、彼らにとって読み取り可能でなければなりません。二次的な要求は、それが私たちに読めるべきであることです。許可されているセマンティクスが得意であり、コードの構造化が得意であれば、ソースコードは私たちにとっても読みやすいはずです。最適なコードにはコメントは不要です。
しかし、すべてのプロジェクトには複雑さが潜んでいるため、複雑さをどこに置くか、どのラクダを飲み込むかを常に決定する必要があります。これらはコメントを使用する場所です。
自己文書化コードは通常、コードが実行していることと正確に一致する変数名を使用するため、何が起こっているのかを簡単に理解できます
ただし、このような「自己文書化コード」はコメントに置き換わることはありません。特に保守性の点で、コードが複雑すぎて自己文書化コードでは不十分な場合があります。
私はかつてこの理論を固く信じていた教授がいました
最初は全員が驚きましたが、理にかなっています。
しかし、状況は、コードで何が起こっているのかを理解できるかもしれませんが、経験の浅い人があなたの後ろに来て何が起こっているのか理解できないかもしれません。これは、コメントが重要になるときです。私たちはそれらが重要だとは思わないことを何度も知っていますが、コメントが不要なケースはほとんどありません。
数学的なコードを書くとき、数学、コードが使用する表記規則、およびそれらがすべてどのように適合するかを説明する、長いエッセイのようなコメントを書くことが時々便利だと感じました。ここで何百行ものドキュメントを話している。
私は自分のコードをできる限り自己文書化するようにしますが、数か月後に再び作業するときは、説明を読んでハッシュを作成しないようにする必要があります。
さて、もちろん、この種の極端な手段はほとんどの場合必要ありません。この話の教訓は、コードごとに異なる量のドキュメントが必要だと思います。一部のコードは、コメントを必要としないほど明確に記述できるため、コメントを使用せずに明確に記述してください。
しかし、多くのコードには意味をなすコメントが必要なので、できるだけ明確に記述し、必要なだけコメントを使用してください...
自己文書化コードはコメントに代わる優れたツールだと思います。コードのあり方や理由を説明するためにコメントが必要な場合は、説明のために修正する必要がある関数名または変数名があります。コメントで不足を補うか、いくつかの変数と関数の名前を変更してコードをリファクタリングするかどうかは、コーダー次第です。
ただし、ドキュメントは、システムが物事を行う方法ではなく、システムの使用方法を説明するために他の人に提供するものなので、ドキュメントを実際に置き換えることはできません。
編集：私（およびおそらく他のすべての人）は、おそらくデジタル信号処理（DSP）アプリが非常によくコメントされるべきだという規定を持つべきです。これは主に、DSPアプリが値の配列を供給し、値を加算/乗算するなどのループに対して本質的に2であるためです...プログラムを変更するには、配列の1つの値を変更します...あなたはその場合にやっている;）
自己文書化コードは、時間の経過とともにコード、コメント、およびドキュメントが分岐するという問題を簡単にオプトアウトします。そして、それは明確なコードを書くことを訓練する要因です（あなたがあなた自身に厳しいなら）。
私にとって、これらは私が従おうとするルールです：
- コードはできるだけ読みやすく、明確にする必要があります。
- コメントは、私が行った設計決定の理由を示す必要があります：なぜこのアルゴリズムを使用するのか、コードが持つ制限など：動作しないとき...（これはコードの契約/アサーションで処理する必要があります）（通常関数/プロシージャ内）。
- 文書には、使用法（呼び出しを呼び出す）、副作用、可能な戻り値をリストする必要があります。 jDocやxmlDocなどのツールを使用してコードから抽出できます。したがって、通常は関数/手順の外側にありますが、記述されているコードに近いです。
つまり、コードをドキュメント化する3つの手段はすべて密接に関連しているため、コードが変更されたときに変更される可能性が高くなりますが、表現が重複することはありません。
いわゆる自己文書化コードの本当の問題は、それが実際に行うことを伝えることです。いくつかのコメントは誰かがコードをよりよく理解するのに役立つかもしれませんが（例えば、アルゴリズムのステップなど）、それはある程度冗長であり、あなたがあなたのピアを納得させることを疑います。
ただし、ドキュメントで本当に重要なのは、コードから直接明らかではないものです：基本的な意図、仮定、影響、制限など。
コードがXを実行していることを一目で判断できるのは、コードがYを実行していないことを判断できるよりもはるかに簡単です。彼はY ...
見た目はよく、明らかですが、実際には入力のすべての基底をカバーしていないコードの例を彼に見せて、彼がそれを見つけたかどうかを確認できます。
私は、あなたの多くがそうするように、真に自己文書化するためには、コードが何らかの形の意図を示す必要があると主張します。しかし、私はまだ誰もBDDに言及していないことに驚いています- 行動駆動開発 。アイデアの一部は、コードの意図を説明する自動化されたテスト（コード）があることです。
優れたドメインモデリング +優れた名前（変数、メソッド、クラス） +コード例（ユースケースからの単体テスト） =自己文書化ソフトウェア
コードに加えて追加のコメントが明確になる理由はいくつかあります。
- あなたが見ているコードは自動的に生成されたため、コードの編集は、プロジェクトが次にコンパイルされるときに破壊される可能性があります
- 簡単ではない実装は、パフォーマンスの向上と引き換えに行われました（ループの展開、高価な計算のためのルックアップテーブルの作成など）。
それは、チームがドキュメントで重視することすべてになります。どのようにではなく、理由/意図を文書化することが重要であり、これは常に自己文書化コードに取り込まれるとは限りません。これらは明らかです-しかし、計算、検索などの理由を表現する必要があります。
また、国籍が異なる場合はチームの違いに注意してください。ディクショナリの違いは、メソッドの命名にintoする可能性があります。
バイセクションサーチ
BinarySearch
BinaryChop
3つの異なる大陸で訓練された開発者から提供されたこれらの3つの方法は、同じことを行います。アルゴリズムを説明したコメントを読むことによってのみ、ライブラリ内の重複を特定できました。
//大したことではないなら、心配しないでください。
//すべてのコメントを書く場合、重要なコメントは表示されません
- メソッドパラメーターのコメント：死ぬ必要があります。これはコードの重複です。
//パラメータは自明である必要があります。
- WTFファクターの想像力：私自身を含む誰かがこれにWTFを言うでしょうか？
ほとんどのドキュメント/コメントは、将来のコードエンハンサー/開発者を支援するのに役立つため、コードを保守可能にします。多くの場合、後で新しい機能を追加したり最適化したりするために、後でモジュールに戻ってきます。当時は、多数のブレークポイントをステップスルーするよりも、コメントを読むだけでコードを理解する方が簡単でした。それに加えて、既存のものを解読するよりも、新しいロジックを考えるのに時間を費やしたいと思います。
コメントが必要なコードを読むことは、私が知らない言語でテキストを読むことに似ています。私は声明を見て、それが何をするのか、またはなぜ理解していない-そして私はコメントを見なければならない。私はフレーズを読んで、それが何を意味するのか理解するために辞書を調べる必要があります。
通常、実行内容を自己文書化するコードを書くのは簡単です。その理由を説明するには、コメントの方が適していますが、ここでもコードの方が適しています。抽象化のすべてのレベルでシステムを理解している場合は、次のようにコードを整理してみてください。
public Result whatYouWantToDo(){
howYouDoItStep1();
howYouDoItStep2();
return resultOfWhatYouHavDone;
}
メソッド名は意図を反映し、メソッド本体は目標を達成する方法を説明します。とにかくそのタイトルで本全体を伝えることはできないため、システムの主要な抽象化、および複雑なアルゴリズム、重要なメソッドコントラクト、アーティファクトをドキュメント化する必要があります。
同僚が作成したコードが本当に自己文書化されている場合-あなたと彼は幸運です。同僚のコードにコメントが必要だと思われる場合は、コメントが必要です。その中で最も重要な場所を開いて、一度読んで、すべてを理解しているかどうかを確認してください。コードが自己文書化されている場合-する必要があります。そうでない場合-同僚に答えを出した後、同僚にその質問がコメントやコードに文書化されていない理由を尋ねます。彼はコードは彼のような賢い人のための自己文書であると主張することができますが、とにかく彼は他のチームメンバーを尊重する必要があります-あなたのタスクが彼のコードの理解を必要とし、彼のコードがあなたに理解する必要があるすべてをあなたに説明しない場合-それは必要ですコメント。
優れた設計構造は、「この関数は一般的です」というコメントがなくても、一部の機能は一般的な用途向けであり、一部はランダムなビジネスロジック向けであることを指摘するのに役立ちます。
ただし、設計と仕様のドキュメントを忘れてはなりません。それらは、コメントで必ずしも必要ではないテキストの多くを持っているか、少なくとも持つべきです。ソフトウェアには多くの場合、ユーザーマニュアルやその他の説明文書もあり、これらはプログラムの動作と同期している必要があります。ユーザーがマニュアルではなくソースコードからソフトウェアが何をするのかを知る必要がある場合、状況はそれほど良くありません。したがって、自己文書化コードは、実際のソフトウェアが文書化されたことを意味しません。
機能のトレーサビリティも考えてください。マニュアルを入手したら、機能をソースコードにトレースして、保守性を高めることができます。マニュアルと仕様はプログラミングに関するものではありませんが、ソフトウェアエンジニアリングに関するものです。ソフトウェアが大きいほど、より多くのエンジニアリングが必要です。
コメントなしでコードが完全に明確でない場合、コードを改善する余地があります。
「不明瞭なコードはコメントしないでください」と言っているわけではありません。 「コードを明確にする」と言っています。
何らかの方法でコードが不明瞭になる場合、thenコメントを使用して補正します。
非コメントキャンプからのいくつかの視点。
「よくコメントされた」（冗長）コードは読みにくく、理解しにくい。一つには、スキャンするテキストが増えるだけです。これにより、CodeBaseを理解する際の認知作業が増加します。機能しないテキストは、コードを表示するために使用できる画面スペースを占有します。
コメントに関するもう1つの大きな問題は、コメントが信頼できないことです。特に古いコードベースでは、コメントの腐敗はビット腐敗よりも早く設定されます。
そしてもちろん、コメントを書くことに関与する努力があります。ときどき1行の明確化を除き、コードのコメントを開始するたびに、2つの罪悪感の1つを得る
- この情報は、全体をサポートするドキュメントに記載する必要があります
- コードをクリーンアップする必要があります
彼が得ているのは、コードが何をしているのかをコメントで説明する場合は、コードの意図を明確にするために書き直すべきだと思います。それは彼が自己文書化コードによって意味するものです。多くの場合、これは長い関数を説明的な関数名で論理的な小さな断片に単純に分割することを意味します。
それはコードがコメントされるべきではないという意味ではありません。つまり、コメントは、コードがそのままの形で記述されている理由を提供する必要があることを意味します。
コードを読みやすくするので、自己文書化コードを実現するために常に努力すべきだと思います。しかし、あなたは物事について実用的でなければなりません。
たとえば、私は通常、すべてのクラスメンバーにコメントを追加します（これにはドキュメントコメントを使用します）。これは、メンバーが何をすべきかを説明しますが、どのようにそれを行うかは説明しません。コード、特に古いコードを読んでいるときに、これはメンバーの目的をすぐに思い出すのに役立ち、特にコードの流れがかなり飛び回る場合は、コードを読んで作業するよりも簡単であることがわかります。
これは私の意見です。私はコメントなしで働いている多くの人々を知っており、彼らはこれが問題ないと思うと言います。しかし、私は彼らに6ヶ月前に書いた方法について誰かに尋ねました、そして、彼らはそれが何をしたかについて正確に言うために数分間考えなければなりませんでした。メソッドがコメント化されている場合、これは問題ではありません。
最後に、コメントはコードと同様にシステムの一部であることを覚えておく必要があります。機能をリファクタリングおよび変更する際には、コメントも更新する必要があります。これは、コメントが間違っていると役に立たないよりも悪いため、コメントを使用することに対する1つの議論です。
純粋に自己文書化されたコードが達成可能であるにもかかわらず、とにかくすべきことを思い浮かぶいくつかのことがあります：
- 「驚くべき」コードは決して持ってはいけません。すなわち。愚かなマクロを使用して物事を再定義するなどしないでください。演算子のオーバーロードを誤用しないでください。これを賢くしようとしないでください。
- 適切な場所でコードを分割します。適切な抽象化を使用します。ローリングバッファー（固定長で、一方の端でアイテムを追加し、もう一方の端でアイテムを削除する2つのポインターを持つバッファー）をインライン化する代わりに、適切な名前の抽象化を使用します。
- 関数の複雑さを低く保ちます。長すぎたり複雑になった場合は、他の関数に分割してみてください。
特定の複雑なアルゴリズムを実装する場合、アルゴリズムを説明するドキュメント（またはリンク）を追加します。しかし、この場合、間違いを犯すのは簡単すぎるため、不必要な複雑さを取り除き、読みやすさを高めるために、さらに熱心になるようにしてください。
私は、すべてまたはまったくというよりも、適切な量のドキュメントの問題だと思います。関数のパラメーターに適切な名前が付けられている場合、多くの場合、パラメーターが何であるかを正確に言う必要はありません。 char * CustomerNameはかなり明白です。パラメーターにアサート値の範囲を使用する場合、それらの範囲も文書化する必要はありません。 IMO、ドキュメンテーションは、明白ではないため説明が必要なすべてのものをカバーする必要があり、ほとんどのコードにはドキュメンテーションが必要です。個人的には、ほとんどの場合、説明的なドキュメントよりも、特定の機能がどのように機能するかを示す例をご覧ください。
ドキュメントはコードベースで最新の状態に維持する必要があるため、ドキュメントのためのドキュメントは時間の無駄になる可能性があります。誰もそれを読んで利益を得ない場合、それを生成しないでください。
System.outを使用して、コードの機能を説明します。そうすれば、印刷して自宅で読むことができます：p
私はこれを好転させます。
彼のコードで理解できないことを自問し、それらを文書化するように頼んでください。そして多分あなたも私たちにいくつかを伝えることができます。
私はかつて大企業に金融スイートを販売しようとしていた男と働いていました。彼らは、彼がソースコードを文書化することを主張し、それに対して彼は30+ページのアセンブラールーチンを作成し、「それは文書化され、見て」と言った-そして彼は13ページにめくり、コメントが1つ増えた。優れた製品、優れた実装者、しかし...
とにかく、上記の重要なコメントはコンテキストを設定することです。このスニペットは、自己文書化されていると述べられています。
> 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)
しかし、私はそれを完全に理解するためのコンテキストが必要です。
コメントは意図を捉えるべきだという点が指摘されていますが、もう少し先に進みます。
どのクラスの問題でも、それを説明するための理想的な（またはほぼそれに近い）語彙と構文があり、そのような問題を抱えている人にそれらを説明するように頼むだけでそれを見ることができます（その人は明確に考えることができると仮定して） 。
その語彙と構文が（クラス、メソッドなどを定義することにより）コンピューター言語のコードに簡単にマッピングされる場合、そのコードは自己文書化できます。また、ドメイン固有の言語であるIMOが作成されました。 （そして、それが「宣言的」の私の荒削りな定義です。）
この理想に失敗すると、問題がコンピューターコードに直接マップされない場合、2つをリンクするために何かが必要です。 IMO、それがコメントの目的です。
そうすれば、問題が変わったときに、変更するコードの対応する部分を見つけることができます。
編集：ところで、私はすべての名詞がクラスになり、すべての動詞がメソッドになるOOP方法論を支持しているわけではありません。私は十分なブロートウェアが構築されているのを見ましたthat way。
あなたの質問に対する私の最善の回答を以下に示します。
自己文書化コードは、クラス、メソッド、関数、および変数名で明確に記述されたコードであり、意図と機能を簡単に理解できるようにします。うまくいけば、それはドキュメントです。
それはcanよくコメントされ文書化されているコードを置き換えますが、私はめったに見ません。多くの場合、プログラマーはこれを行うのに十分だと考えていますが、それらをノックダウンする最良の方法は質問を始めることです。彼らがあまりにも多くの説明を始めなければならない場合、彼らのコードは十分に明確ではありませんでした。コードが何をするのかを知るためにコードを読む必要はないはずです。
それが良いいくつかの状況があるかもしれません。コードが小さくてシンプルな場合は、ドキュメントを追加することで物が散らかることがあります。
アルゴリズムを含むコードにはコメントを含める必要があります。ほとんどの場合、元のプログラマーでさえ、数ヶ月前に長い関数を書いたときに考えていたことを思い出せません。
これは素晴らしい質問です。コメントを許可した最初のプログラミング言語にまでさかのぼります。コードは、可能な限り自己文書化する必要があります。明らかなことを指摘しているコメントは削除する必要があります。特定のメソッドまたはコードのセクションの意図、目的、および使用法を理解しやすくするコメントは、問題の言語またはコードにあまり精通していない私たちにとって非常に貴重なものです。 APIドキュメントの生成を可能にする構造化コメントは良い例です。チェックボックスがチェックされているかどうかを確認するIFステートメントにコメントしないでください。チェックボックスがチェックされているかどうかを確認していることを教えてください。コメントで自明なことを繰り返すと、私たちの宇宙で最悪の無駄なキーストロークです。
//For example, the above text deals with what is a useful comment
ここでは非常に混合された入力のようです:)
私は、新しい開発のために擬似コードプログラミングプロセスを使用します。これにより、コードは実質的に自己文書化されます。私は、新しいコードを記述してから拡張するときにのみ、疑似コードを書き始めます。これはベストプラクティスやそのようなことを言っているわけではありませんが、サードパーティ、レビューアなどに行く場合、コードのドキュメントがたくさん必要なことがわかっている場合に便利なテクニックを強調しています場合によっては、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
自己文書化コードは愚かです。数週間、数か月、またはgasp年後にコードを再確認する必要があった人は、それを知っています（私の場合は数日です）。 （おそらく、このアイデアを推進している人はまだ耳の後ろで濡れている！？！？！）
意味のある説明的なデータ名を使用し、コードをインテリジェントにファクタリングし、なぜあなたがやったことをやったのかについてのヒントを残し、より豊かで充実した人生を送るでしょう。
しかし...私はかつてビル・ゲイツに起因する引用を読みました：「コードIS文書」。
図を移動します。
自己文書化コードは、簡単に理解できるコードです。変数の命名は、コードを自己文書化するのに大いに役立ちますが、私は、複雑なロジックを小さな小さなチャンクに分解し、その情報を冗長で有益な名前を持つ別のメソッドにリファクタリングすることが最善の策だと思います。その後、複雑なメソッドは、実行するステップのリストになります。小さなプライベートヘルパーメソッドは、独自のメソッド名で十分にドキュメント化され、複雑なメソッドは、実行される一連の抽象ステップとしてドキュメント化されます。実際には、この戦略を常に完全に適用できるとは限らないため、コメントは依然として非常に便利です。さらに、理解しやすいコードを作成するのに役立つツールを完全に放棄しないでください。
自己文書化コードは、コメントが不要になるほど明確なコードです。私は小さな例を挙げます：
//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
}
最後のスニペットは、コメントなしでは解読するのが非常に難しいでしょう。もっと工夫された他の例を想像することができます。