コードドキュメントを自動生成する論理的な理由はありますか？[閉まっている]

自動ドキュメント生成はさまざまなツールで実行できますが、GhostDocはその中でも最も優れたツールの1つです。ただし、定義上、生成されるものはすべて冗長です。それは方法など、クラス、および出力の英語の名前を見てとるかもしれないより冗長にそれらを説明します。最良の場合、読者が頭の中ですでにできることを行います（ここからの例）：

/// <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で生成されるドキュメントは定型文です（IDEで新しいOOクラスを作成すると、コンストラクタなどでクラスの定型文が作成されるのと同様です）。ドキュメントの有用な部分は、定型文を追加した後に続くものです。

あなたは職場ですべてを文書化する必要がありますが、同僚はその周りの完璧な方法を見つけたようです。

静的に型付けされた言語では、Javadocスタイルのドキュメントは作成者向けではなく、消費者向けです。自動生成により、作成者は他の人が利用できるドキュメントを簡単に維持できます。

静的に型付けされた言語を使用していて、サードパーティが使用するためのライブラリを作成していない場合、自動生成はあまり買わず、私の経験ではほとんど使用されません。動的に型指定された言語を使用している場合、内部使用のみであっても、javadocスタイルのドキュメントを使用して型をドキュメント化することがよくありますが、自動生成では型が認識されないため、ボイラープレートの手動コピーを回避できます。

いずれにしても、自動生成を完成品の生産と考えないでください。それはあなたのためのボイラープレートを生成すると考えてください。したがって、手動で行う変更は重要です。

コードドキュメントを自動生成する論理的な理由はありますか？

誰の視点から？

私が会社または開発グループを運営していた場合、正当な理由はありません。私は「コメントが理由を説明する必要があります」キャンプに忠実です。人々にクラス/関数/プロパティをコメントさせることは、時代遅れになり、読者を誤解させ、読み取り可能なコードを作成しない言い訳として使用されるなど、価値がありません。これらのコメントは、それらの記述、コードの読み取り、およびそれらによって引き起こされるバグの両方の時間を無駄にします。JavaDocスタイルのAPIドキュメントがコメントを行う理由であると主張する人もいますが、その議論の下でも、コードのごく一部はパブリックAPIの一部である必要があり、JavaDocは実際のAPIドキュメントの代替ではありません。

開発者として、私の意見にもかかわらず、これらの場所でコメントを必要とするいくつかの場所で働いてきました。私は誰も使用しないくだらないものを書く時間も忍耐力もないので、代わりにGhostDocを使用します。これにより、その時間を費やして、重要なことを実際に行うことができます。企業ポリシーを変更するよりもはるかに効率的です。

GhostDocを使用して見つけたもう1つの良い点は、それが私の名前が良いことのチェックとして機能することです。GhostDocが関数の適切なドキュメントを生成できない場合、関数またはパラメーター名が貧弱かもしれないというにおいです。このためだけにこのツールを使用するわけではありませんが、とにかく時間を無駄にせざるを得ない場合は、ちょっとした副作用です。

編集：元の質問を誤解しました。ドキュメンテーション（つまり、非コードドキュメント）を生成することは非常に価値があると思いますが（下のDoxygenに関する元の回答を参照）、コメントの自動生成（GhostDocが実際に行っていること）は私にとっては非常識です。プログラムがコメントされていないソースコードを読み、それを本当に明確にするコメントを書くことができると誰が期待するのか、私には理解できません。

非常に「スマート」なコメント生成ユーティリティをプログラムして、特定のパターンを認識し、「方法」スタイルのコメントを生成できると考えられます。たとえば、Knuthの分散計算アルゴリズムを認識し、それがどのように機能し、なぜ単純なアルゴリズムが適切でないのかを説明するコメントを提供できます。おそらく、このようなユーティリティは、標準的なオブジェクト指向のデザインパターン（Abstract Factoryなど）を認識し、どのパターンが使用され、どのクラスがどの役割を果たしているかを示すコメントを挿入するようにプログラムできます。

しかし、私の意見では、最も有用なコメントは、コード自体がこれを表示する必要があるため、「どのように」何かが機能するかを説明しませんが、「なぜ」コメント、特定のことを「なぜ」行うかを説明します。以下のコメントでDavid Hammenが述べたように、「なぜ」コメントを生成するためには、ユーティリティは「プログラマーの心を読む」必要があります。明らかにこれは不可能です。

ただし、指定された例に基づいて、GhostDocは真の「方法」スタイルのコメントを作成するタスクさえ達成していないようです。だから、私の意見では、役に立たないよりも悪いのです。なぜなら、それが生成するものは、（2番目の例のように）無意味で誤解を招く可能性があるからです。

元の答え：自動ドキュメント抽出および書式設定が良いアイデアである理由

私のソフトウェアチームはDoxygenを使用しています。これの主な理由は、コードの機能/動作/などの非ソースコード（つまり、プログラマではない人が読める）のドキュメントが必要なことですが、これをソースコード自体に統合するよりも良い方法だと感じていますそれを2番目のドキュメントとして維持してください。これにより、ドキュメントをソースコードと同期させることができます（もちろん、完全に保証することはできませんが、自動化はあまり行われません）。ドキュメント作成のオーバーヘッドを最小限に抑えます（コードのドキュメントは、コード自体を含むファイル）。

したがって、Doxygenの使用の焦点は、コード自体から情報を抽出することではなく、ソースコードのドキュメントをソースコード自体に可能な限り近づけることです。

これにより、単一のツールを使用して、コードベース全体を説明する「操作理論」と、ソフトウェア製品を説明するが実際には「コード文書」を含まない「リリースノート」のセットを作成できます。典型的な感覚。

コードの動作に関するソースコード以外のドキュメントが必要になる理由については、次の2つの理由があります。

• 当社の製品は単なるソフトウェアではありません。それは、いくつかの派手なレーザーや流体工学を含む多くのハードウェアコンポーネントを統合する複雑なツールです。ソフトウェアのバックグラウンドがあまりないエンジニアには、コードの内部がどのように振る舞うかを正確に理解する必要があり、「ソースコードを読む」ことでこれを達成することはできません。
• 社内で義務付けられているものもあれば、連邦政府によって法的に義務付けられているものもあります。品質プロセスは非常に価値があり、有用ですが、無視できない量のオーバーヘッドが伴います。その一部は、ソフトウェアチームがこの種のソフトウェアの詳細なドキュメントを提供する義務です。繰り返しますが、このドキュメントをコード自体と統合すると、オーバーヘッドが最小限に抑えられ、ドキュメントを最新の状態に保つことができます。

2番目の箇条書きは、管理者がソースコードのすべての部分に（品質に関係なく）一部のドキュメントが存在することを確認するという安心感（/自慢する権利）を求める他のいくつかの回答とほぼ同じです。ただし、この方法では、外部から義務付けられたドキュメントに実際に正当な利点があるという事実は無視されます。

確かに、自動化されたドキュメントは、コード作成者が作成した洞察に富んだ適切な説明を再現できる場合に特に役立ちます。それ以外の場合は、単なる自動化されたフォーマッターです。

しかし、書式設定は無駄ではありません。ラージッシュコンポーネントのパブリックメソッドを一度に見つめ、ソートし、完全であることを保証できることには価値があります。frobnickミューテーターが必要で、そこにない場合は、ソースコードを渡さずにミューテーターが存在しないことがわかります。（ネガティブな結果にも価値があります。あなたは何かをしなければならないことを知っています。そして、あなたはウェイドする必要がなかったので、あなたはそれをするより多くの時間を持っています。）

そのため、はい、自動ドキュメント生成は何らかの価値を追加します。確かに管理者が想定しているほど多くはなく、通常は本当に優れたコピーエディターほどではありませんが、何もありません。

この形式では、役に立たないよりも悪いのですが、それは公開署名のみに依存しているためです（Javadocの場合、API文書を読んでいる人なら誰でも見ることができます）。

ただし、メソッドの本体も考慮した自動ドキュメントツールを作成することもできます。概念実証として、文書化されたメソッドから呼び出された他のメソッドのリストをJavadocに追加する不完全な小さなEclipseプラグインを作成しました。（もちろん、すべての呼び出しではなく、パッケージごとにフィルターを定義できます。）

そして、まったく知らないコードベースを精神的にマッピングするときに、それが実際に非常に便利であることがわかりました。確かに、これは非常に限られたユースケースですが、間違いなく助けになりました。

その経験に基づいて、質問に対する答えは「はい」ですが、もっとスマートなツールが必要です。

更新：もちろん、追加の質問（ドキュメントを作成する前に尋ねるべき質問）は、対象読者です。そのAPIのクライアント向けに公開APIをドキュメント化する場合、Javadocに入れるものは技術的にはAPIの一部であるため、この実装の詳細をすべて追加することは大したことではありません。

しかし、対象ユーザーが同じ製品で作業している他の開発者である場合、特定のフィールドを変更または読み取るメソッドなど、実装の詳細に関する情報を自動的に追加することは受け入れられ、かなり便利です。

私は他の環境については知りませんが、他の人が書いた大規模な（多くの場合オープンソース）PHPプロジェクトに関しては、phpXRefは絶対的な命の恩人です（特にドキュメントがオンラインに置かれ、Googleがインデックスを作成できる場合）。

ひどくコメントされたプロジェクトでさえ、少なくとも、物事が定義されている場所と使用されている場所を追跡するのに役立ちます（たとえば、リファクタリングの場合）。

よくコメントすると、結果のページはコードベースの完璧な聖書に近い形になります（とにかく私の用途のため）。

さらに、私の好みのIDEはコメントブロックを自動生成し（/ **と入力した場合）、コメント作成作業の約75％を行います。自分が何をしているのかを他の人（そして将来の私）に説明しなければならなかったからといって、コーダーの生涯にわたってコミットするのを止められた愚かなことは驚くべきことです。ドキュメントジェネレータに対する私のコメントがメソッドよりも大きい場合、これは通常、十分なコーヒーがなかったことを意味し、少し難しく考えたいかもしれません。

これらの同じコメントブロックはインライン補完の「ヘルプ」テキストも作成するため、関数呼び出しを書いているときに（他のコーダーが）期待していたものを正確に見ることができます。これは私にとって非常に大きな生産性の向上です（特に、他の有用な開発者が「善のためにXをやる」と書いている稀なエッジケースでは、多くの苦痛を軽減できます）。

複雑な（多くの場合、名前が間違っている）PHPプロジェクトで指定された予期される入力タイプと、あまり使用されないメソッドでの引数の順序を持​​つことの有用性を十分に強調することはできません。独自のコードを使用しても、時代に触れたことのないものに対してどの引数を指定したかを常に思い出すことはできません。

ある例では、再発する問題の原因は、以前の開発者にひどく反映されている何らかの理由で、いくつかの関数や定数でさえ非常に多くの場所で定義されていたということでした。それがプロジェクトから立ち去る兆候でした。

私が参加する前に始まった大規模なプロジェクトでは、どの開発者（クラスファイルに名前と電子メールのタグが付けられていると仮定して）がクラスを作成し、適切な開発者を見つけて話すことができるのは非常に役立ちます。

自動タスクリスト-@todoタグ（自分が作業しているプロジェクトでよくあることです）を使用すると、ドキュメントでさらに作業が必要なもの（または欠落していると認められている機能）を追跡できます。繰り返しますが、私のIDEはこれを追跡し、それだけで最初に注意が必要なものについての良いガイドとして機能します。

最後に（そして私にとって非常に重要なことです）、すべてを書き留め、一部の（多くの）コーダーが変更をコミットし、ドキュメントメンテナーと話をしないときに、それを最新に保とうとする重要なオーバーヘッドを取り除きます。

その理由は次のとおりです。

• 後の開発者の時間を節約し、
• 関数が呼び出される（および定義される）場所を追跡し、
• 愚かなコーディングの発見、
• 明らかに欠落しているものを見つける（別の人が指摘したように）
• リファクタリングの単純化（あまり楽しくない）
• （多くの場合）開発者が何をしようとしているかを把握する（メモを残していると仮定）。
• プロジェクトが複雑で、複数のライセンスが実行される（面白くない）場合、どのセクションにどのライセンスが適用されるかをすぐに確認できます。確かに、これは副ボーナスです。
• プロジェクトファイルについて話す相手のアイデアを得る。
• 自動タスクリスト

また、ボタンに触れるだけで先のとがった髪のボスを満足させる価値を過小評価しないでください。

要するに、「自動ドキュメンテーションコメント」は私のコーディング習慣にとって不可欠です。それは足の不自由だと思う人は多いと思いますが、私が言っていることを正確に知っている人がかなりいることも確信しています。phpXRef（および私のお気に入りのIDE）を発見するまで、どのように生き延びたのかわかりません。

多くの場合、ドキュメンテーションジェネレーターを使用して定型または「スタンドイン」コメントを作成し、後で実際の開発者が修正します。私は、Eclipseのauto-JavaDoc関数を使用して、パラメータータイプを含むヘッダーコメントを生成し、既に入力されている値を返し、ドキュメントの「肉」を追加するだけです。

C＃開発者としてStylecopを使用します。これは、すべてのクラス、メソッドなどのコメントを義務付けています。ツールを使用してこれらのコメントを自動生成します。ほとんどの場合、ツールによって生成されたコメントで十分であり、オブジェクトの名前（Personクラスが持つIDフィールドなど）から推測できます。

しかし、明白でない方法についてさらにコメントしたい場合は、定型的なドキュメントとその機能に関するいくつかの説明を簡単に拡張できます。例として、私はPersonクラスにFirstName + Lastnameを返すメソッドを持っていますが、両方の一方が欠落している場合に何が起こっているかについてのドキュメンテーションを少し追加しました。

要するに、ジェネレーターが提供するテキストを変更しないと、定型文書は有害になると思います。その場合、それは単なるラインノイズです。しかし、それらをテンプレートとして見ると、自分自身やあなたの消費者に有益で有益なコメントを提供するための基準を下げます。コメントを自動生成せずに書くことができますか？確かに、フォーマット（C＃の場合はかなり冗長で手作業で生成するのは面倒です）に従う必要があり、このコメントを実際に提供する可能性は低くなります。

トートロジーを避ける

コードに関する何らかのドキュメントが必要なのは、メソッド/関数が何かをしている理由を説明するときだけです。名前は、それが何をしているのかで十分です。

イディオムではないことを行っている場合、または最小限の驚きの原則に違反している場合は、ドキュメントが必要です。

情報を出力するための単なるフォーマッターである自動生成されたドキュメントは、コードの利用者からほとんど要求されています。Javadocはこれを非常にうまく行います。

すべてを手動で文書化する必要はありません

getXXX / setXXXメソッドのようなものは自明であるはずなので、それらが存在することを単に知らせる自動生成ドキュメントは好評です。

少なくとも「自動」のようなコード文書は、アプリケーションを理解しようとする人々にとって最も一般的な分母を表しています。

最も洗練されたユーザーは、自動コードドキュメンテーションを歓迎しません。彼らはむしろ、彼らに何を（ほとんど）伝える必要があるかを伝える「ターゲットを絞った」ドキュメントを持っているでしょう。

最も洗練されていないユーザーは、反対の理由でそれを高く評価しません。とにかく彼らはそれを理解しません。

自動コードドキュメンテーションの最も「好意的な」ユーザーは、「少しの知識」が危険なことです。このオーディエンスには、ほとんどの「管理」タイプが含まれます。それが主なオーディエンスであれば、自動コードドキュメンテーションは良いことかもしれません。

「ドキュメントを生成する理由」に対する簡単な答えは、MSDNを表示することで簡単に答えられます。

APIドキュメンテーションがないライブラリを使用するプログラムを作成しようとすることを想像してください。それは悪夢です。MSDNは、ソースコードとコメントから生成でき、開発者に不可欠なリソースを形成できる種類のドキュメントの優れた例です。

アプリケーションを作成している場合（つまり、他の人が使用するライブラリではない場合）、気にしない場合があります-しかし、それでも、内部専用の大規模なアプリケーションにはライブラリの束が含まれていませんとにかく？このようなチームに参加するときは、閲覧可能なAPIドキュメントを用意しておくと役立ちます。

ツールはドキュメントを作成しませんが、とにかく手動で書き出す必要のある定型文を提供します。一部のツール（doxygenなど）は、ダイアグラムと参照リスト（たとえば、呼び出された関数と呼び出し関数の）も生成します）ソースコードを見ても簡単に発見されないでしょう。

明らかに、文書化されたものには実用的な常識を適用し、プロパティとマイナー関数は無視できます（そしてツールでも生成からスキップされます）が、いつでも誰でも「ソースコードがあれば十分です」と言うべきではありません。