9

XMLコメントを使用することの長所を理解できません。コードの外部で優れたドキュメントに変換できることは知っていますが、はるかに簡潔なDOxygen構文でも同じことが実現できます。私の意見では、XMLコメントは間違っています。理由は次のとおりです。

  1. 彼らは一般的にコメントとコードを難読化します。（人間が読むのはもっと難しいです）。
  2. 「summary」と「/summary」は追加の行を使用するため、1つの画面で表示できるコードが少なくなります。
  3. （削除）

では、その理由は何だったのでしょうか。単純なDOxygen構文ではなくXMLが.NETで好まれたのはなぜですか。

4

6 に答える 6

10
  1. ideはコメントを取得し、そのメソッドを使用するときにそれらを表示します。
  2. C＃をプログラムする人なら誰でも、おそらくXMLコメントシステムに精通しているでしょう。新入社員のために学ぶことはほとんどありません。

DOxygenが優れていると言っているのではなく、xmlコメントシステムが誰にとってもなじみ深いというだけであり、それは大いに役立ちます。それはあなたがするために新入社員を訓練しなければならないことのほんの1つ少ないことです。

変数にコメントを付けないままにする限り。あなたにとって明らかなことは、他の誰か（または6か月後のあなた）にはわかりません。

さて、あなたが何を求めているのかわかりました。

  1. 難解なコメント。色分けが役立ちます。個人的には、灰色のテキストをすばやくスキャンして、xmlテキストを読み取る必要がない限り、緑色のテキストのみを読み取ります。（少なくとも私の設定では）。

  2. 私たちは大きなモニターを持っているので、一般的に画面上により多くのコードを表示します。（一般的に人々を再訓練するよりも大きなモニターを購入する方が安いです）。これについてのもう1つの点は、一度に1つの関数のみをアクティブに表示していることです。したがって、その関数全体がページに収まる場合は、コードが表示されないことにそれほど苦しむことはないでしょう。関数が長いと、それが問題になることがわかります。

  3. 可能な場合は、要約コメントを1行に配置します（それほど大きくないと仮定します）。これにより、使用スペースが削減されます。

  4. DOxygenがこれを行うかどうかはわかりませんが、コメントを折りたたんで邪魔にならないようにすることができます。

于 2010-04-06T13:00:54.710 に答える
7

XMLドキュメントの主な仕事は、ドキュメントを生成することではありません。クラスのクライアントに適切なIntelliSense情報を提供することです。生成された.xmlファイルをアセンブリと一緒に出荷します。

于 2010-04-06T13:14:56.247 に答える
4

.NETでXMLコメントを使用することの長所

これらはC＃コンパイラとVisual Studioによってネイティブにサポートされており、印刷、オンライン、およびインテリセンスのドキュメントで使用するためにAPIをドキュメント化するための単一の場所を提供します。

MSDNマガジンのこの記事には、次のように記載されています。

すべてのプロジェクトには、ドキュメントに満足していない人がいます。チームリーダーはソースでより多くのコメントを求め、テクニカルライターはコード設計に関するより多くの記述情報を求め、品質保証は機能仕様を確認したいと考えています。これらのドキュメントがすべて実際に作成されている場合でも、すべてのドキュメントの同期を維持するという戦いがあります。

形式は必ずしも理想的ではありませんが、XMLドキュメントのコメントは、これを実現できるような豊富な構文を提供します。

代わりにC＃でDOxygenをサポートしてみませんか？

DOxygenよりも既存のXMLシステムが選択された理由については、これは主にDOxygenがGPLの下でリリースされているためだと思います。つまり、Visual StudioとC＃コンパイラもそのようにリリースする必要があります。GPLの条件を考慮してやりたい。

于 2010-04-06T13:17:39.243 に答える
3

私がさらに驚異的なのは、ghostdocプラグインの人気です。メソッド名に基づいてコメントを自動的に生成できるのであれば、なぜコメントがあるのでしょうか。

Steve Yeggeは、過剰なコメントは初心者プログラマーの兆候であり、私は彼に反対するのに苦労していると言います。

于 2010-04-06T13:01:18.080 に答える
1

プロジェクトでそれらを使用する必要はありません。

これらは、たまたまVisual Studioに統合されている標準であり、StyleCopを使用すると、強制することができます。これがここの美徳です。

ただし、DOxygenを使用することにした場合は、何も止められません。一貫していることを確認してください。

于 2010-04-06T13:01:31.117 に答える
1

ここで本当に正しい答えはありませんimo。どちらのシステムも実際には他のシステムよりも「優れている」わけではありません。どちらも最終的に同じ仕事をするため、コードド​​キュメントを生成できます。

最終的な出力は、それぞれに対してまったく同じ方法でフォーマットできます。また、サポートするラベルなどに関してはほぼ同じ機能を備えているため、ここでの個人的な選択に依存します。

個人的には、XMLコメントは人間が読める形式で、論理的で、使いやすいと感じています。ただし、Visual Studioでスタブを自動的に生成して入力するだけでよいという利点があり、優れたサポートが提供されます。画面上で多くのスペースを占有しないように、それらを折りたたむ。VIまたはsome_other_IDEでのバックグラウンド編集から来た人は、異なる意見を持っていると確信していますが、どちらにも実際の利点はありません。

つまり、実際には、使用しているIDEと、あなたとあなたのチームが何を使用しているかによって異なります。

ここで、MicrosoftがVisual Studio内でXMLコメントと緊密に統合することを選択した理由を尋ねている場合、それは別の質問です。おそらくそれは次の事実によるものです：VS内で実装する方が簡単です（既存のコードを再利用してコメントを生成/読み取り、インテリセンスなどを構築できるため）、「標準」に固執する傾向があります「とにかく（それが彼ら自身のものであろうと業界のものであろうと）、そしてジェフが述べたようにライセンスの理由も。

マイクロソフトがVS内で使用している製品を追加するだけで、「サンドキャッスル」と呼ばれます。これは、社内のXMLドキュメント生成ツールです。独自のwikiページ@http ://docproject.codeplex.com/Wikipageがあります

于 2010-04-06T14:43:36.217 に答える