interfaceで定義したメソッドのXMLコメントの書きかた

Question

 

タイトルの通り、インターフェースを使った時のXMLコメントの書き方に困っています。

重複してインターフェースと実装クラスに同じコメントを残すのは、もろにDRYな感じがして好ましく思えません。

JavaDocなどではinheritDocタグで対応するような部分だと思うのですが、C#はどうやったらいいのでしょうか？

 

以下、コードの例を示します。

 

/// <summary>
/// インターフェースです.
///
/// <para>
///
/// </para>
/// </summary>
/// <author>my name</author>
/// <version>1.0.0</version>
/// <since>2011/05/25</since>
public interface ISample
{

    /// <summary>
    /// テストのメソッド。
    /// </summary>
    /// <param name="test">テスト引数</param>
    void TestMethod(args test);

}


internal class A{

    ///
    /// ???
    ///
    internal void TestMethod(args test)
    {
        // ....
    }

}

 

internal class B{

    ///
    /// ???
    ///
    internal void TestMethod(args test)
    {
        // ....
    }

}

 

 

A、B、インターフェースで同じコメントは最悪のケースですが、

拡張したからAとBは詳細なコメントでも残すべきなのでしょうか？　それも、また変な感じがしますが・・・・・・。

 

以上、よろしくお願いします。

 

 

Answer 1

実装時に詳細なコメントを記載するかどうかは、コーディングする上での方針として各自（や、各会社）が決めるものでしょう。

.NET Framework のクラスライブラリでは、（結果的に型名などの違いだけかもしれませんが）詳細なコメントに書き換えられていることのほうが多いように思います。私は個人の作業では ghostdoc という Visual Studio のプラグインを使用してインターフェースと同じコメントを書いています。

 

Answer 2

 

返信ありがとうございます。

 

コーディングする上での方針として各自（や、各会社）が決めるもの

＞＞今回はC#のテストも兼ねているので、一番よい方法を探しています。なので、方針に融通が効く分、他言語に劣る結果なのが一番困るといった具合です。

 

インターフェースと同じコメントを書いて

>>同じコメントを書いてしまうと、コメントを修正した時などに問題にあっさり整合性が取れなくなると思うのですが、それは無視して構わないということですか？

 

Answer 3

> 同じコメントを書いてしまうと、コメントを修正した時などに問題にあっさり整合性が取れなくなると思うのですが、それは無視して構わないということですか？

ここだけ反応しました。インターフェイスを実装するなら、インターフェイスと実装クラスの <summry> はほぼ変わらないのでは。よほどのことがない限り変える必要がないように思えます。
もしここを大きく変えるようなら、インターフェイスの設計自体がおかしいのではないでしょうか。
<summry> と <remarks> の例は MSDN ライブラリが参考になります。MSDN ライブラリの例を見ても、<summry> はほぼ共通、<remarks> ・・・いわゆる解説の部分を変えるケースが多いように思えます。

以下 MSDN のクラスライブラリの例（インターフェイス → 実装）を二つほど挙げます。

IInputElement.Focus メソッド
UIElement.Focus メソッド

IButtonControl.NotifyDefault メソッド
Button.NotifyDefault メソッド

ちなみに私は、ドキュメントの生成に Sandcastle を使ってます。
http://journal.mycom.co.jp/articles/2008/07/15/Sandcastle/index.html

---

ひらぽん http://d.hatena.ne.jp/hilapon/

Answer 4

追伸です。
最近は、プロジェクトで仕様の変更・追加が激しいため、詳細なコメントは書いていません。
<summry> に簡単な記述だけですませるようにしています。

---

ひらぽん http://d.hatena.ne.jp/hilapon/

Answer 5

こんにちは。

とても興味深いトピックだと思います。
私も皆さんのご意見をお伺いしたいです。

私の今まで所属したプロジェクトでは（そんなに多くないですけど）
概ね実装は実装で新たに詳しく書くことが多かったです。

自分のプロジェクトの場合はSandcastle前提で実装側に

        /// <summary>
        /// <see cref="ClassLibrary1.Interface1.Method" />の実装です。
        /// </summary>
       
で書いたり、

        /// <inheritdoc />
        public string InheritedMethod(){ ...

でごまかしちゃうことも多かったりします。
でもコーディングの時にインテリセンスに詳しい説明が出ないのが何ともイケてなかったり・・・。

Visual Studioの<summary>コメントにインターフェースのものをコピーしてくれる機能があれば良いのに、
と思ったことは何度もあります。
この機能がVisual Studioに乗ることを強く願っています。
（私が知らないだけかもしれませんが。。。）

# 使ったことないですがGhostDocなるツールもあり、使い方によってはできるのかもしれません。。
# ■ツールを使ったドキュメント作成技法（後編） － ＠IT
# http://www.atmarkit.co.jp/fdotnet/special/agiledocument02/agiledocument02_01.html

Answer 6

ひらぽんさん

返信ありがとうございます。

＞インターフェイスを実装するなら、インターフェイスと実装クラスの <summry> はほぼ変わらないのでは。よほどのことがない限り変える必要がないように思えます。
＞もしここを大きく変えるようなら、インターフェイスの設計自体がおかしいのではないでしょうか。

おっしゃられる通り、インターフェイスの設計が誤りがあった場合、継承したクラスの説明まで変更する必要があるということです。

そんなのは悪い設計する人が悪いってことだと思いますが、どうしてもやってしまう時はやってしまうものだと思います。（体調が常に良いわけではないように）

そうなると、やはりここは重複するようなコードは私は悪い慣例に思えます。

 

＞<summry> と <remarks> の例は MSDN ライブラリが参考になります。

＞MSDN ライブラリの例を見ても、<summry> はほぼ共通、<remarks> ・・・いわゆる解説の部分を変えるケースが多いように思えます。

なるほど、解説の部分を変えるやり方をしているんですね。気づきませんでした。

一応、継承のコメントに対する情報が全然足りないと思って質問した次第です。最初に書いておけばよかったですね、すいません。

 

Answer 7

Tetsuaki　Uchidaさん

返信ありがとうございます。

＞<see cref="ClassLibrary1.Interface1.Method" />の実装です。

これは、今のところ一番答えに近いですね。うまくリンクするドキュメントを吐けるなら代替案としていい感じだと思いました。

 

＞/// <inheritdoc />

これは、自分で定義したタグですよね？　面白いですが、あまり意味がないですね。

 

 

私は仕事の中でコメントを残さないのは、別のプログラマにひどい迷惑をかけることだと理解しています。

自分だけのプログラムならSummaryだけで十分かもしれませんが、やはりそれだけでは恐ろしい選択肢にも思えています。

すいませんが、いろいろな意見、よろしくお願いします。

Answer 8

> コメントを残さないのは、別のプログラマにひどい迷惑をかけることだと理解しています

 

うちは逆かも？ 仕事では、メンテナンスできないコメントは書くなと指導しています。間違っている内容や古い内容、他のメソッドのコピペなどのコメントが記載されていることが、可読性をかなり下げることになるため、できるだけコメントは書かない。コメントがなくても理解できるような名前付けや実装を行うようにと指導しています。

 

Answer 9

＞/// <inheritdoc />

これは、自分で定義したタグですよね？　面白いですが、あまり意味がないですね。

あ、そうじゃないです。
Sandcastleの機能で、
<inheritdoc />タグを付けるとインターフェースの方に書いたコメントをまんまコピーしてヘルプファイルを作ってくれます。
<remarks>タグを追加することもできます。
ヘルプドキュメントとしては完璧なんですが
ソースコメントとしては意味が無いのが痛いです・・・;;

Answer 10

本筋ではないところですが、紹介まで。

Visual Studioの<summary>コメントにインターフェースのものをコピーしてくれる機能があれば良いのに、
と思ったことは何度もあります。
この機能がVisual Studioに乗ることを強く願っています。

そう思う人々がいるせいか、C#/VB.NET 向けアドインの ReSharper にはその機能がありますね。
関数名に合わせて Alt+Enter すると基底クラス（インターフェース）からコメントをコピーするという機能が列挙される。

# ただ、ReSharper の導入は地道にショートカットキーを設定するか、英語版の UI を使うかしないといけないというハードルがあります。

---

質問スレッドで解決した場合は、解決の参考になった投稿に対して「回答としてマーク」のボタンを押すことで、同じ問題に遭遇した別のユーザが役立つ投稿を見つけやすくなります。

Answer 11

> コメントを残さないのは、別のプログラマにひどい迷惑をかけることだと理解しています

私も K. Takaoka さんの意見に近いです。コメントなくても判りやすいようコードを書くのにかなりこだわってます。
クラスの責任を明確にし極力単一の責任を持たせるようにする。
メソッドも極力分割して短い行で収まるよう実装し、クラス名やメソッド名も汎用的かつ判りやすい名前を付けるよう心がければ、 コメントが少なくても保守性は高くなると思ってますし、実際突発的な仕様変更にも柔軟に対処できます。

実際いまのプロジェクトも毎週２～３個当たり前のように仕様変更出てますが・・・まるでアジャイル！ｗ
でも楽しみながら、月の半分近く定時で上がっても余裕で対処できるんですよね。

あと命名規則やクラス定義等は以下のガイドラインに沿って実装すれば、少々コメント少なくても改修する際さほど混乱を招かないかと・・・まぁスキルにもよりますが（汗

クラス ライブラリ開発のデザイン ガイドライン
http://msdn.microsoft.com/ja-jp/library/ms229042.aspx

ガイドラインをより詳しく解説してる書籍はこちら

.NETのクラスライブラリ設計
http://www.amazon.co.jp/dp/4891006765

これはチームの全員が熟読する価値があります。

---

ひらぽん http://d.hatena.ne.jp/hilapon/

Answer 12

>Azuleanさん

ご紹介ありがとうございます！

ReSharper 、さっそく試してみます！

Answer 13

＞/// <inheritdoc />

なるほど、そうなんですね。早合点でした、すいません。

 

SandCastleでの書き出しがいいですが、インテリセンスが問題なんですね・・・・・・。

関連してAzuleanさんのReSharperは自分も試してみようと思います。ありがとうございます。

 

Answer 14

＞コメントなくても判りやすいようコードを書くのにかなりこだわってます。

興味のある面白い内容なので、ちょっと内容とはズレてますがコメントです。

私はクラスやメソッドの機能をシンプルにすることは、結果的にコードの読みやすさに繋がると思いますが、

そもそも、C#の場合はJITコンパイラの最適化のために、きれいなコードを書いてあげるものだと理解しています。

分かりやすくコードを書くというのはニュアンスとして近いですが、機能を細分化してシンプルで単純なものにしてあげるのは言語（パフォーマンス）上、注意してあげるべきだと思っています。

メンテナンスできないコメントは書くな、というのは納得ができています。

クラス名やメソッド名も、きちんとルール付けするのはその通りだと思います。

ただ、ごゃごちゃと長いコメントを残すよりも、この辺りのテクニックは資料を挙げてもらった通り、プログラマに技量が必要で、プログラマに依存するものだとも思うので、怖い部分は消えきらなくもあります。

今度はチーム全員の技量が信頼できる状態でないと、恐ろしいという感じです。

 

挙げて頂いたURLのものは読んでみます。ありがとうございます！！

 

Answer 15

> そもそも、C#の場合はJITコンパイラの最適化のために、きれいなコードを書いてあげるものだと理解しています。

これは、誰も理解してくれないような気がします。少なくとも、例外的に最適化を見越したコードを書くことはあっても、こんなこと基準にコードを書くようなことがあってはならないと思います。

Answer 16

＞少なくとも、例外的に最適化を見越したコードを書くことはあっても、こんなこと基準にコードを書くようなことがあってはならない

 

たぶん想像するような、見越したというものではないですね。

JITコンパイラが混乱するような、オリジナリティ溢れる長ったらしいものを書いてもいいことはない、という内容かと。

詳細はEffectiveC#４．０にも載っている内容です。なので、大きく間違っているものではないと思いますが。