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

全般的な情報交換
-
タイトルの通り、インターフェースを使った時の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は詳細なコメントでも残すべきなのでしょうか? それも、また変な感じがしますが・・・・・・。
以上、よろしくお願いします。
- 種類を変更済み 山本春海 2011年6月3日 7:59 情報を集めているようでしたので、種類をディスカッションに変更させていただきました。
すべての返信
-
> 同じコメントを書いてしまうと、コメントを修正した時などに問題にあっさり整合性が取れなくなると思うのですが、それは無視して構わないということですか?
ここだけ反応しました。インターフェイスを実装するなら、インターフェイスと実装クラスの <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/ -
こんにちは。
とても興味深いトピックだと思います。
私も皆さんのご意見をお伺いしたいです。
私の今まで所属したプロジェクトでは(そんなに多くないですけど)
概ね実装は実装で新たに詳しく書くことが多かったです。
自分のプロジェクトの場合は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 -
ひらぽんさん
返信ありがとうございます。
>インターフェイスを実装するなら、インターフェイスと実装クラスの <summry> はほぼ変わらないのでは。よほどのことがない限り変える必要がないように思えます。
>もしここを大きく変えるようなら、インターフェイスの設計自体がおかしいのではないでしょうか。おっしゃられる通り、インターフェイスの設計が誤りがあった場合、継承したクラスの説明まで変更する必要があるということです。
そんなのは悪い設計する人が悪いってことだと思いますが、どうしてもやってしまう時はやってしまうものだと思います。(体調が常に良いわけではないように)
そうなると、やはりここは重複するようなコードは私は悪い慣例に思えます。
><summry> と <remarks> の例は MSDN ライブラリが参考になります。
>MSDN ライブラリの例を見ても、<summry> はほぼ共通、<remarks> ・・・いわゆる解説の部分を変えるケースが多いように思えます。
なるほど、解説の部分を変えるやり方をしているんですね。気づきませんでした。
一応、継承のコメントに対する情報が全然足りないと思って質問した次第です。最初に書いておけばよかったですね、すいません。
-
Tetsuaki Uchidaさん
返信ありがとうございます。
><see cref="ClassLibrary1.Interface1.Method" />の実装です。
これは、今のところ一番答えに近いですね。うまくリンクするドキュメントを吐けるなら代替案としていい感じだと思いました。
>/// <inheritdoc />
これは、自分で定義したタグですよね? 面白いですが、あまり意味がないですね。
私は仕事の中でコメントを残さないのは、別のプログラマにひどい迷惑をかけることだと理解しています。
自分だけのプログラムならSummaryだけで十分かもしれませんが、やはりそれだけでは恐ろしい選択肢にも思えています。
すいませんが、いろいろな意見、よろしくお願いします。
-
本筋ではないところですが、紹介まで。
Visual Studioの<summary>コメントにインターフェースのものをコピーしてくれる機能があれば良いのに、
と思ったことは何度もあります。
この機能がVisual Studioに乗ることを強く願っています。そう思う人々がいるせいか、C#/VB.NET 向けアドインの ReSharper にはその機能がありますね。
関数名に合わせて Alt+Enter すると基底クラス(インターフェース)からコメントをコピーするという機能が列挙される。# ただ、ReSharper の導入は地道にショートカットキーを設定するか、英語版の UI を使うかしないといけないというハードルがあります。
質問スレッドで解決した場合は、解決の参考になった投稿に対して「回答としてマーク」のボタンを押すことで、同じ問題に遭遇した別のユーザが役立つ投稿を見つけやすくなります。 -
> コメントを残さないのは、別のプログラマにひどい迷惑をかけることだと理解しています私も K. Takaoka さんの意見に近いです。コメントなくても判りやすいようコードを書くのにかなりこだわってます。
クラスの責任を明確にし極力単一の責任を持たせるようにする。
メソッドも極力分割して短い行で収まるよう実装し、クラス名やメソッド名も汎用的かつ判りやすい名前を付けるよう心がければ、 コメントが少なくても保守性は高くなると思ってますし、実際突発的な仕様変更にも柔軟に対処できます。実際いまのプロジェクトも毎週2~3個当たり前のように仕様変更出てますが・・・まるでアジャイル!w
でも楽しみながら、月の半分近く定時で上がっても余裕で対処できるんですよね。あと命名規則やクラス定義等は以下のガイドラインに沿って実装すれば、少々コメント少なくても改修する際さほど混乱を招かないかと・・・まぁスキルにもよりますが(汗
クラス ライブラリ開発のデザイン ガイドライン
http://msdn.microsoft.com/ja-jp/library/ms229042.aspxガイドラインをより詳しく解説してる書籍はこちら
.NETのクラスライブラリ設計
http://www.amazon.co.jp/dp/4891006765これはチームの全員が熟読する価値があります。
ひらぽん http://d.hatena.ne.jp/hilapon/ -
>コメントなくても判りやすいようコードを書くのにかなりこだわってます。
興味のある面白い内容なので、ちょっと内容とはズレてますがコメントです。
私はクラスやメソッドの機能をシンプルにすることは、結果的にコードの読みやすさに繋がると思いますが、
そもそも、C#の場合はJITコンパイラの最適化のために、きれいなコードを書いてあげるものだと理解しています。
分かりやすくコードを書くというのはニュアンスとして近いですが、機能を細分化してシンプルで単純なものにしてあげるのは言語(パフォーマンス)上、注意してあげるべきだと思っています。
メンテナンスできないコメントは書くな、というのは納得ができています。
クラス名やメソッド名も、きちんとルール付けするのはその通りだと思います。
ただ、ごゃごちゃと長いコメントを残すよりも、この辺りのテクニックは資料を挙げてもらった通り、プログラマに技量が必要で、プログラマに依存するものだとも思うので、怖い部分は消えきらなくもあります。
今度はチーム全員の技量が信頼できる状態でないと、恐ろしいという感じです。
挙げて頂いたURLのものは読んでみます。ありがとうございます!!