コードのドキュメント：多すぎますか？

https://stackoverflow.com/questions/288298

08-07-2019
|

質問

.NETソースのコードドキュメントはどれだけ多すぎますか？

いくつかの背景：私はSOでここに投稿した他の質問のいくつかで話した大きなコードベースを継承しました。「機能」の1つこのコードベースの1つはGodクラスで、数十個の静的メソッドを含む3000行以上のコードを持つ単一の静的クラスです。 Utilities.CalculateFYBasedOnMonth（）から Utilities.GetSharePointUserInfo（）から Utilities.IsUserIE6（）までのすべてです。書き換える必要がない、すべてにリファクタリングするのは良いコードですライブラリの適切なセット。私はそれを計画しました。

これらのメソッドは新しいビジネスレイヤーに移行しており、このプロジェクトでの私の役割は、他の開発者によるメンテナンスのためにシステムを準備することなので、しっかりしたコードのドキュメント化を考えています。これらのメソッドにはすべてインラインコメントがありますが、XMLコメント形式のコードドコがありません。 GhostDocとSandcastle（またはDocument X）のコンボを使用して、非常に優れたHTMLドキュメントを作成し、SharePointに投稿することができます。これにより、開発者はコード自体をナビゲートせずにコードの動作についてより理解できます。

コード内のドキュメントの量が増えると、コードをナビゲートすることが難しくなります。 XMLコメントによって、たとえば各メソッドでより単純な // comment を使用するよりも、コードの保守が難しくなるのではないかと思い始めています。

これらの例は、ドキュメントXサンプルから：

        /// <summary>
        /// Adds a new %Customer:CustomersLibrary.Customer% to the collection.
        /// </summary>
        /// <returns>A new Customer instance that represents the new customer.</returns>
        /// <example>
        ///     The following example demonstrates adding a new customer to the customers
        ///     collection. 
        ///     <code lang="CS" title="Example">
        /// CustomersLibrary.Customer newCustomer = myCustomers.Add(CustomersLibrary.Title.Mr, "John", "J", "Smith");
        ///     </code>
        ///     <code lang="VB" title="Example">
        /// Dim newCustomer As CustomersLibrary.Customer = myCustomers.Add(CustomersLibrary.Title.Mr, "John", "J", "Smith")
        ///     </code>
        /// </example>
        /// <seealso cref="Remove">Remove Method</seealso>
        /// <param name="Title">The customers title.</param>
        /// <param name="FirstName">The customers first name.</param>
        /// <param name="MiddleInitial">The customers middle initial.</param>
        /// <param name="LastName">The customers last name.</param>
        public Customer Add(Title Title, string FirstName, string MiddleInitial, string LastName)
        {
            // create new customer instance
            Customer newCust = new Customer(Title, FirstName, MiddleInitial, LastName);

            // add to internal collection
            mItems.Add(newCust);

            // return ref to new customer instance
            return newCust;
        }

そして：

    /// <summary>
    /// Returns the number of %Customer:CustomersLibrary.Customer% instances in the collection.
    /// </summary>
    /// <value>
    /// An Int value that specifies the number of Customer instances within the
    /// collection.
    /// </value>
    public int Count
    {
        get 
        {
            return mItems.Count;
        }
    }

だから私はあなたから疑問に思っていました：NDoc（RIP）やSandcastleのようなものを使用することを目的として、XMLコメントでコードのすべてを文書化しますか？そうでない場合、ドキュメントを取得するものとしないものをどのように決定しますか？ APIのようなものには明らかにdocoがありますが、保守のために別のチームに引き渡すコードベースについてはどうですか？

どうすればいいと思いますか？

解決

ここでの問題の大部分は、MSが私たちに押し付けた冗長で凝ったXMLドキュメント構文であると思います（JavaDocもそれほど良くはありませんでした）。それをどのようにフォーマットするかという問題は、かなりの程度、適切な量とは無関係です。

コメントにXML形式を使用することはオプションです。 DOxygenまたはさまざまな形式を認識する他のツールを使用できます。または、独自のドキュメント抽出プログラムを作成します-合理的な仕事をすると思うほど難しくはなく、良い学習体験です。

どれだけ難しいのかという質問。コードを維持するために掘り下げている場合、自己文書化コードのアイデアは素晴らしいと思います。単にクライアントである場合、特定の関数がどのように機能するかを理解するためにコードを読む必要はありません。もちろん、データの種類と名前には多くの情報が暗黙的に含まれていますが、そうではないものがたくさんあります。たとえば、オブジェクトへの参照を渡すと、何が期待されるかがわかりますが、null参照の処理方法はわかりません。または、OPのコードで、引数の先頭または末尾の空白がどのように処理されるか。文書化されるべきこの種の情報は、通常認識されるよりもはるかにあると思います。

私には、関数の目的と、関数のすべての事前条件と事後条件、その引数、およびプログラミング言語の構文では表現できない戻り値を記述する自然言語のドキュメントが必要です。

他のヒント

コードを肥大化させる必要がないとは誰も言及していません。XMLドキュメントは別のファイルに入れることができます。

/// <include file="Documentation/XML/YourClass.xml" path="//documentation/members[@name='YourClass']/*"/>

そして、Addメソッドには、その上に余分なXML /コメントを含めることはできません。または、要約だけが必要な場合（別のファイルとマージされるため）。

これは、JavadocやPHP / Javascriptで見られる派生物であるゴミ形式よりもはるかに強力です（ただし、JavadocはXML構文への道を開きました）。さらに、利用可能なツールははるかに優れており、ヘルプドキュメントのデフォルトの外観は読みやすく、カスタマイズしやすいです（ドックレットを作成し、そのプロセスをSandcastle / DocProject / NDocと比較することで言えます）。

ここで、新しいライブラリを維持するものと新しいライブラリを消費するものとの間に重大な格差が生じています。

新しいアプリケーションを作成し、これらの標準ライブラリを使用する場合、ソースコードをある場所からコピーして問題を引き起こす可能性があるのではなく、ライブラリの安定したバイナリを取得してアプリケーションにインポートする必要がありますコードが変更された場合。その場合、「自己文書化」のいずれにもアクセスできません。メソッドの名前と入出力パラメータ以外の機能、およびオートコンプリート機能がオンになっていない種類のIDEを使用している場合でも、それらは公開されません。

つまり、上記のコード例では、見た目は問題ないと思います。コード自体の中で物事は冗長ではなく、名前は自己文書化されています。一方、必要な要約/パラメータデータはすべて揃っているため、ライブラリを使用する人が重要な情報をすべて手元に持つことができるように、しっかりしたドキュメントを構築できます。残念ながらXMLはかなり肥大化していますが、ほとんどの開発者はすべての要約コンテンツを簡単に閲覧して、メソッド内の実際のコードを調べることができると思います。

Jeffには、コメントについての非常に良い記事があります（またはコメントしないでください）。

http://www.codinghorror.com/blog/archives/001150.html

質問に答えていないように思えますが、コードは可能な限り自己文書化することが有効なポイントだと思います。

すべてのパブリックメソッドを自分のコードに文書化する傾向があります。 GhostDocを使用すると、これは簡単になります。そして、ソースコードを編集するときの混乱を減らすために、通常はまず「アウトラインモード」に移動してコメントを折りたたみます。（つまり、Visual Studioのアウトライン＆gt; [定義に折りたたむ]コマンドを使用します）。

Sandcastleを試したことは一度もありませんが、XMLでコメントしたメソッドに対してIntellisenseが提供する快適さに本当に感謝しています。

私は常にXML / Javadoc形式のコメントを選択します。賢明な形式（通常HTML）でAPIドキュメントを閲覧できることが大好きだからです。

実際のソースコードの閲覧には問題になりますが、Visual Studioは必要に応じてXMLコメントを折りたたむのが一般的に非常に賢明であるため、これは一般に小さな問題であることがわかりました。

繰り返さないでください。

最初の例では、より良いメソッド名を使用し、コメントは一切使用しないでください。
2番目の例にはコメントを付けないでください。

最初のメソッドの名前は、新しいオブジェクトが割り当てられたことを反映する必要があります。

その動作が各追加のフレームワーク全体で標準である場合、このメソッドAPIドキュメントではなく、より高いレベルで文書化する必要があります。それ以外の場合は、名前を変更します。

コメントは情報を追加する必要があり、ノイズで非表示にしないでください。また、XMLで必要な場合はコメントが必要です。そして、彼らは価値を追加します。

見たくない：「カウントを返す」 countという名前のメソッドの場合。

すべてのパブリック関数は、コードベースに精通している人が明確に理解できる必要がありますが、コードを掘り下げることなく特定のセクションでは理解できません。

関数の機能を説明する短い行を記述する必要がある場合、関数/クラスの名前が間違っている可能性があります。その場合、名前は自明でなければなりません

説明するために複数の短い文が必要な場合、おそらく良いコメントです

段落を取る場合、関数はおそらく不明瞭な名前のほかに多くのことを行っています。

通常は、コメントの側に誤りがある方がよいでしょうそれらが正確であることを確認した場合。不正確および/または保守不能なコメントは、コメントなしよりも悪い

これらのルールを適用する：

最初の例：＆quot; // create new customer instance＆quot;冗長です。コードは非常に明確です。他のコメントは完璧です。彼らはコードが何を操作しているのか、それが何であるのかを明確にします

2番目の例では、コメントは無駄な努力であり、読みにくくしています。必要なのは、関数に適切な名前を付けることだけです。あいまいな「カウント」ではありません。それは貧弱な命名です。

最近、重要な＆quot;指令＆quot;がある場合、発信者はXを実行する必要があることを示す調査を実施しました;多くの仕様（たとえば、「このメソッドはYとZを意味するXを実行します」）内では、読者がディレクティブを見逃すという非常に高いリスクがあります。実際、長いドキュメントを見ると、一緒に読むことをスキップします。

少なくとも、重要なものを分離するか、タグ付けを使用します（Javaを使用している場合は質問してください）。

それはすべてあなたの会社が使用している標準に依存しますが、私の乗組員のために、あなたの2番目の例のようにすべての関数の先頭にドキュメントを作成します（Visual Studio 2008で＆quot; / ＆quot;サブまたは関数の上部に3回連続でキーを押してください!!）。

最初の例は過剰です。特に、各行がコメントされている下の数行です。ただし、ここで多く使用しているため、関数のヘッダーにあるものは役に立つかもしれません。そして、他の多くのプログラマーから私が知ることができるものから、いくらか標準的であるように見えます。

自己コメントのコードとメソッドのオーバーロードをコメントすることを推奨しないコーディング標準を見てきました。 YMMVの場合、「フィールド_numberOfCarsは、車の数」を表す整数です。過剰なコメントにつながるタイプのコメントです。

ドキュメントを生成するためのヘッダー内のコメントは良いことです。コードにコメントを入れて、自分がしていることをしている理由を説明することも、通常は良いことです。あなたがしたことを言い換えて冗長なコメントを入れるのは良いことではありません

これまでに示したのは非常に多すぎです。自己支持して削除してください！

コードは、まず意味のあるメソッド名とパラメーター名を使用して、自己文書化する必要があります。示した例では、

public Customer Add（タイトルタイトル、文字列FirstName、文字列MiddleInitial、文字列LastName）は、 'Count'と同様に、何が起こっているのかを完全に理解できます。

このようなコメントは、あなたが指摘したように、それ以外の場合はコードが読みやすいものの周りの純粋にノイズです。ほとんどの開発者は、あいまいな自動生成されたAPIドキュメントを積み重ねるよりも、すぐにコードを調べて使用します。いつも！

ところで、「コードのクリーン」によると、（すばらしい本、BTW）、ソースコードに埋め込まれているコメント内でHTML / XMLマークアップを使用することは避けてください。ホバー時にIDEが気の利いたドキュメントを作成できたとしても、ソースを参照するだけでは気が散りすぎて読めないと見なされます。

ライセンス： CC-BY-SA と帰属

所属していません StackOverflow