コードドキュメントを自動生成する論理的な理由はありますか？
ドキュメントの自動生成はさまざまなツールで実行でき、GhostDocは最も有名なツールの1つです。ただし、定義により、生成されるものはすべて冗長です。メソッド、クラスなどの名前を見て、mightがより詳細に説明する英語を出力します。最良のケースでは、読者がすでに頭でできることを実行します（例は here から取得）：
/// <summary>
/// Initializes a new instance of the <see cref="Person"/> class.
/// </summary>
public Person() ...
最悪の場合、名前の意味をヒューリスティックに理解しようとする試みで実際に誤解を招く奇妙なドキュメントが生成される可能性があります。
/// <summary>
/// Riches the text selection changed.
/// </summary>
/// <param name="richTextBox">The rich text box.</param>
private void RichTextSelection_Changed(System.Windows.Controls.RichTextBox richTextBox) ...
GhostDocの態度は「本質的にはある種の正式なXMLドキュメントを持っている方が良い」と思われますが、そのドキュメントが100％冗長である場合、どうして？せいぜい大量のスペースを無駄にするだけではないですか？
私の職場では、すべてを文書化する必要があり、ほとんどの場合、GhostDocの自動生成ドキュメントを使用します。これを行いますか？実際にドキュメントを自分で作成しないのであれば、単にコードをドキュメント化しないままにしない合理的な理由はありますか？
[...]すべてを文書化し、ほとんどの場合、GhostDocの自動生成ドキュメントを使用します。これを行いますか？実際にドキュメントを自分で作成しないのであれば、単にコードをドキュメント化しないままにしない合理的な理由はありますか？
いいえ。GhostDocによって生成されるドキュメントはボイラープレートです（OOクラスをIDEで作成すると、コンストラクターなどでクラスのボイルプレートが作成されます） ）ドキュメントの有用な部分は、ボイラープレートを追加した後に続くものです。
あなたがする必要がある職場ですべてを文書化している間、同僚はその周りに完璧な方法を見つけたようです。
静的に型付けされた言語では、Javadocスタイルのドキュメントは作成者向けではなく、コンシューマ向けです。自動生成により、作成者は他の人が使用するためのドキュメントを保守しやすくなります。
静的に型付けされた言語を使用していて、サードパーティが使用するためのライブラリを作成していない場合、自動生成はあまり効果がなく、私の経験ではめったに使用されません。動的に型付けされた言語を使用している場合は、javadocスタイルのドキュメントがタイプのドキュメント化に使用されることが多く、内部使用のみですが、自動生成はタイプを認識しないため、ボイラープレートを手動でコピーする手間が省けます。
いずれにせよ、自動生成を完成品の生産とは考えないでください。これはボイラープレートを作成するものと考えてください。手動で行う変更は重要です。
コードドキュメントを自動生成する論理的な理由はありますか？
誰の観点から？
私が会社または開発グループを運営している場合、正当な理由はありません。私は「コメントは説明しなければならない理由」キャンプに固執しています。人々にクラス/関数/プロパティのコメントを強制することは、価値がないよりも悪いです。古くなったり、読者を誤解させたり、可読コードを作成しない言い訳として使用されたりするためです。これらのコメントは、それらの作成、コードの読み取り、およびそれらによって引き起こされたバグの両方に時間を浪費しています。 JavaDocスタイルのAPIドキュメントがコメントを行う理由であると主張する人もいますが、その引数の下でも、コードのごく一部がパブリックAPIの一部である必要があり、JavaDocは実際のAPIドキュメントの代わりにはなりません。
開発者として、私の意見にも関わらず、これらの場所でrequireコメントができる場所をいくつか扱ってきました。私は誰も使用しないだらけの束を書く時間も忍耐力もないので、代わりにGhostDocを使用します。これにより、その時間を実際に重要なことに費やすことができます。企業ポリシーを変更するよりもはるかに効率的です。
私がGhostDocを使用して見つけたもう1つの良い点は、それが私の名前が正しいことのチェックとして機能することです。 GhostDocが関数の適切なドキュメンテーションを生成できない場合、それは私の関数またはパラメーター名が不十分である可能性があるにおいです。このツールをjustに使用することはありませんが、とにかく時間を浪費するようになっている場合は、これはいい小さな副作用です。
[〜＃〜] edit [〜＃〜]：元の質問を誤解しました。documentation（つまり、非コードdocuments）を生成することは非常に価値があると思いますが（Doxygenに関する元の回答を参照）以下）、自動生成comments（これはGhostDocが実際に行うことです）は、私には非常識に聞こえます。プログラムがコメント化されていないソースコードを読み取り、それを本当に明確にするコメントを書くことができると誰もが期待する理由を理解できません。
非常に「スマートな」コメント生成ユーティリティcouldは、特定のパターンを認識して「方法」スタイルのコメントを生成するようにプログラムされていると思います。たとえば、それは Knuthの分散計算アルゴリズム を認識し、それがどのように機能するか、および単純なアルゴリズムが適切ではない理由を説明するコメントを提供できます。おそらく、そのようなユーティリティは、正規のオブジェクト指向のデザインパターン（Abstract Factoryなど）を認識し、どのパターンが使用され、どのクラスがどのような役割を果たしているかを示すコメントを挿入するようにプログラムすることもできます。
しかし、私の意見では、最も有用なコメントは、コード自体がこれを表示するはずなので、何かが「どのように」機能するかを説明しませんが、「why」コメントは、「なぜ「特定のことが行われています。以下のコメントでDavid Hammenが述べたように、「なぜ」コメントを生成するには、ユーティリティは「プログラマの心を読む」必要があります。明らかにこれは不可能です。
しかし、与えられた例に基づいて、GhostDocは本当の「方法」スタイルのコメントを作成するタスクすら達成していないようです。ですから、私の意見では、それがdoes生成するものは非常に不可解で誤解を招く可能性があるため（2番目の例のように）、役に立たないよりも悪いです。
元の回答：自動ドキュメンテーション抽出とフォーマットが良いアイデアである理由
私のソフトウェアチームはDoxygenを使用しています。これの主な理由は、non-source-code（つまり、プログラマー以外が読むことができる）コードfeatures/behavior/etcのドキュメントが必要なことですが、2つ目のドキュメントとして維持するよりも、これをソースコード自体に統合する方が良いと感じています。これにより、ドキュメントをソースコードと同期させることができ（もちろん、完全に保証することはできませんが、はるかに自動化されていません）、ドキュメントの作成のオーバーヘッドを最小限に抑えます（コードの一部のドキュメントを簡単にに組み込むことができるため）コード自体を含むファイル）。
したがって、Doxygenの使用の焦点は、コード自体から情報を抽出することではなく、ソースコードのドキュメントをソースコード自体にできるだけ近づけることです。
これにより、単一のツールを使用して、コードベース全体を説明する「操作理論」と、ソフトウェア製品を説明する「リリースノート」のセットの両方を作成できますが、実際には実際の「コードドキュメント」は含まれていません。典型的な感覚。
コードの動作についてソースコード以外のドキュメントが必要になる理由については、2つの理由があります。
- 私たちの製品は単なるソフトウェアではありません。これは、いくつかの豪華なレーザーや流体工学を含む多くのハードウェアコンポーネントを統合する複雑なツールです。exactlyコードの内部がどのように動作するかを十分に理解し、「ソースコードを読み取る」ことで達成できないと伝えるには、ソフトウェアのバックグラウンドのないエンジニアが必要です。この。
- 私たちはかなりの数の品質規制に従う必要があります。その中には会社によって義務付けられているものと、連邦政府によって法的に義務付けられているものがあります。品質プロセスは非常に価値があり、役立つ場合がありますが、無視できないほどのオーバーヘッドが含まれます。その一部は、ソフトウェアのこの種の詳細なドキュメントを提供するソフトウェアチームの義務です。繰り返しになりますが、このドキュメントをコード自体と統合すると、オーバーヘッドが最小限に抑えられ、ドキュメントを最新の状態に保つことができます。
2番目の箇条書きのポイントは、ソースコードのすべての部分に（品質に関係なく）いくつかのドキュメントが存在することを知っているという安心感（自慢する権利）を望んでいるマネージャーについて他の2つの回答が示したポイントとかなり似ています。ただし、この方法でフレームを作成すると、外部から要求されたドキュメントには実際に正当な利点がいくつかあるという事実は無視されます。
確かに、自動化されたドキュメントは、コードの作成者が記述した洞察に満ちた適切な説明を再現できる場合に特に役立ちます。それ以外の場合は、自動化されたフォーマッターにすぎません。
しかし、書式設定は無意味ではありません。 1つの視線で大きなコンポーネントのパブリックメソッドを見つけ、並べ替え、完全であることを保証できることに価値があります。 frobnickミューテーターが必要で、そこにない場合は、ソースコードを調べなければ、knowはありません。 （否定的な結果にも価値があります。何かをしなければならないことはわかっていて、手を振る必要がなかったので、それを行うにはより多くの時間があります。）
したがって、はい、自動ドキュメント生成によりsome値が追加されます。確かに、マネージャが想定するほど多くはなく、通常、本当に優れたコピーエディタほどではありませんが、何もではありません。
他の環境については知りませんが、大規模な（多くの場合オープンソース）場合、PHP他の人が書いたプロジェクトの場合、phpXRefは絶対に救命です（特に、ドキュメントがオンラインに置かれている場合）とGoogleはそれをインデックスに登録できます）。
不適切にコメントされたプロジェクトでさえ、少なくとも定義されている場所とそれらが使用されている場所（たとえば、リファクタリング時）を追跡するのに役立ちます。
よくコメントされていると、結果として得られるページは、コードベース（とにかく私の用途）にぴったりの聖書に近くなります。
さらに、私の好みのIDEは、コメントブロックの自動生成を行います（/ **と入力した場合）。これにより、コメント作業の約75％が行われます。私が何をしているのか他の人（そして将来私）に説明しなければならなかったからといって、コーダーの存続期間中にコミットするのを止められました。ドキュメントジェネレーターに対するコメントがメソッドよりも大きい場合、これは通常、十分なコーヒーがなく、もう少し難しいと思うかもしれません。
これらの同じコメントブロックは、インライン補完の「ヘルプ」テキストも作成するため、関数呼び出しを記述しているときに（他のコーダーによって）期待された内容を正確に確認できます。これは私にとって大きな生産性の向上です（特に、他の役立つ開発者が「善のためにXをする/しない」と書いたEdgeのまれなケースでは、多くの苦痛を節約できます。
予想される入力タイプを複雑な（そしてしばしば間違った名前が付けられている）PHPプロジェクトとあまり頻繁に使用されないメソッドでの引数の順序で）指定することの有用性を十分強調することはできません。自分のコードでも、ある時代に触れたことのないものに対して私がどのような議論をしたかをいつも思い出すことはできません。
ある例では、再発する問題の原因が、以前の開発者に悪い影響を与える何らかの理由で、いくつかの関数や定数さえも非常に多くの場所で定義されていることを意味していました（追加された「楽しみ」のためにある程度の不整合がある） 。それはプロジェクトから離れる合図でした。
参加する前に開始した大規模なプロジェクトでは、どの開発者（クラスファイルに名前と電子メールのタグを付けたと仮定）がクラスを作成したかを確認でき、適切な開発者を見つけて話すことができると非常に役立ちます。
自動タスクリスト-@todoタグを使用すると（自分が作業しているプロジェクトでよく見られる）、ドキュメントでさらに作業が必要なもの（または不足していることが認められている機能）を追跡できます。繰り返しますが、IDEはこれを追跡し、それだけで、最初に注意が必要なことについての良いガイドとして機能します。
最後に（そして私にとって非常に重要です）、すべてを書き出して、一部の（多くの）プログラマーが変更をコミットし、ドキュメントの保守担当者と話さない場合にそれを最新の状態に保つことの重要なオーバーヘッドを取り除きます。
つまり、理由は次のとおりです：
- 後の開発者の時間を節約し、
- 関数が呼び出された（および定義された）場所を追跡する、
- ばかげたコーディングを見つけ、
- （別の人が指摘したように）何かが明らかに欠けているときを見つけること、
- リファクタリングの簡素化（あまり面白くない）
- （多くの場合）開発者が何をしようとしていたのかを理解する（彼または彼女がいくつかのメモを残したと仮定して）。
- プロジェクトが複雑で複数のライセンスが実行されている（面白くない）場合、どのライセンスがどのセクションに適用されるかをすばやく確認できます。確かに、これは副次的なボーナスです。
- プロジェクトファイルについて誰と話すかについてのアイデアを得る。
- 自動タスクリスト
また、先のとがった髪のボスをボタンに触れるだけで満足させることの価値を過小評価しないでください。
簡単に言うと、「自動ドキュメントコメント」は私のコーディング習慣にとって不可欠です。それが不自由だと思う人はたくさんいると思いますが、私が言っていることを正確に知っているかなりの数の人がいるのと同じくらい確かです。 phpXRef（および私のお気に入りのIDE）を発見する前に、私がどのように生き残ったかはわかりません。
この形式では、役に立たないよりも悪くなりますが、それは、パブリック署名のみに依存しているためです（Javadocの場合、APIドキュメントを読んでいる人なら誰でも見ることができます）。
しかし、メソッドの本体も考慮した自動ドキュメンテーションツールを作成することも可能です。概念の証明として、ドキュメント化されたメソッドから呼び出された他のメソッドのリストをJavadocに追加する、不完全な小さなEclipseプラグインを作成しました。 （もちろんすべての呼び出しではありません。たとえば、パッケージごとにフィルターを定義できます。）
また、まったく知らないコードベースをメンタルマッピングする場合にも、非常に便利だと実感しました。確かに、それは非常に限られたユースケースですが、間違いなく助けとなりました。
その経験に基づくと、質問への答えは次のとおりです。はい、しかし、もっと賢いツールが必要です。
pdate：もちろん、追加の質問（ドキュメントを作成する前に確認する必要がある質問）は、対象読者を誰にするかです。そのAPIのクライアントのパブリックAPIを文書化する場合、Javadocに入力するものはすべて技術的にAPIの一部であるため、この実装の詳細をすべて追加することは大いに不可です。
ただし、対象読者が同じ製品に取り組んでいる他の開発者である場合、特定のフィールドを変更または読み取るメソッドなどの実装の詳細に関する情報を自動的に追加することは、受け入れ可能であり、かなり有用です。
多くの場合、ドキュメントジェネレータを使用して、定型のコメントまたは「代わりの」コメントを作成し、後で実際の開発者が修正します。私はよくEclipseのauto-JavaDoc関数を使用して、パラメータータイプと戻り値が既に入力されているヘッダーコメントを生成し、ドキュメントの「肉」を追加します。
C＃開発者として、私はすべてのクラス、メソッドなどのコメントを要求するStylecopを使用します。ツールを使用してこれらのコメントを自動生成します。ほとんどの場合、ツールによって生成されるコメントは十分であり、オブジェクトの名前によって推測できます。 PersonクラスにはIDフィールドがあります。
しかし、明白でない方法についてさらにコメントしたい場合は、ボイラープレートのドキュメントとそれが何をするかについてのいくつかの説明を拡張するのは非常に簡単です。例として、PersonクラスにFirstName + Lastnameを返すメソッドがありますが、両方が欠落しているときに何が起こっているのかについて少しドキュメントを追加しました。
簡単に言うと、ジェネレーターから提供されたテキストを変更しないと、ボイラープレートドキュメントは有害になる可能性があると思います。その場合、それは単なるラインノイズです。しかし、それらをテンプレートとして見ると、自分自身または消費者に適切で役立つコメントを提供するための基準が低くなります。自動生成せずにコメントを書いてもらえますか？確かに、しかしあなたはこのフォーマットを守る必要があります（C＃の場合、手作業で生成するのはかなり冗長で面倒です）と、このコメントを本当に提供する可能性が低くなります。
トートロジーを避ける
コードについて何らかの種類のドキュメントが必要なのは、理由を説明するときだけです。メソッド/関数が何かをしているので、whatやっています。
慣用的ではないことを行っている場合、または 最小驚きの原則 に違反している場合は、ドキュメントが必要です。
情報を出力するための単なるフォーマッターである自動生成ドキュメントは、コードの利用者からほとんど要求されています。 Javadocはこれを非常にうまく行います。
すべてを手動で文書化する必要はありません
GetXXX/setXXXメソッドのようなものは自明でなければならないので、それらが存在することを通知するだけの自動生成ドキュメントは好評です。
コードドキュメンテーションは、少なくとも「自動」の種類であり、アプリケーションを理解しようとする人々にとって最も一般的でない特徴です。
最も洗練されたユーザーは、自動コードドキュメンテーションを高く評価しません。彼らはむしろ彼らに何を（ほとんど）伝える必要があるかを彼らに伝える「ターゲットを絞った」文書を持っているでしょう。
最も洗練されていないユーザーは、逆の理由でそれを高く評価しません。彼らはとにかくそれを理解しないでしょう。
自動コードドキュメンテーションの最も「感謝する」ユーザーは、「少しの知識」が危険なものであるユーザーです。彼らは、ドキュメンテーションを理解しているかもしれませんし、理解していないかもしれませんが（そうである可能性は高いですが）、このオーディエンスには、ほとんどの「管理用」タイプが含まれます。それが主なオーディエンスである場合、自動コードドキュメントが良いかもしれません。
「なぜドキュメントを生成するのか」に対する単純な答えは、MSDNを表示することで簡単に答えることができます。
APIドキュメントがないライブラリを使用するプログラムを書こうとしているところを想像してみてください。それは悪夢でしょう。 MSDNは、ソースコードとコメントから生成でき、開発者にとって不可欠なリソースを形成できる種類のドキュメントの良い例です。
アプリケーションを作成している場合（つまり、他のユーザーが使用するライブラリではない場合）、気にならないケースがあるかもしれませんが、それでも、内部専用の大きなアプリケーションに、ライブラリの束が含まれていない場合があります。とにかく？そのようなチームに参加するときは、いくつかの参照可能なAPIドキュメントがあると役に立ちます。
ドキュメンテーションを作成するツールはありませんが、いずれにせよ手動で作成する必要のあるボイラープレートを提供します。一部のツール（doxygenなど）は、ダイアグラムと参照リスト（たとえば、呼び出された関数と呼び出し関数のリスト）も生成します）ソースコードを見ても簡単には発見されません。
ドキュメント化されるものには明らかに実用的な常識を適用する必要があります。プロパティとマイナー関数は無視できます（ツールでも生成からスキップできます）が、いつでも「ソースコードがあり、ドキュメントで十分」と誰もが言うべきではありません。 。