認識子の命名とコメント付けの一般注意事項とDoxygenのMarkdownサポート
前回の記事で、
「自分は、ルールだから仕方なくコメントを付ける目的よりも、認識子にそれなりに相応しい名前を付けるというのを目的に使っている。」
(中略)
「特に、インテリセンスのみ重視なら、summaryとparam、それにreturnsがあれば十分だが、それはデフォルトコメントでほぼOK。ダメなら、もっと相応しい命名があるってこと。」
と書いた。
基本的には、ガイドラインを守ればよい。
具体的にどういうことかを見てみよう。
ドキュメントコメントとインテリセンス
インテリセンスで表示されるドキュメントコメント要素は以下の3種類。
当然だが、XML Documentation形式である。
XML ドキュメント コメント (C# プログラミング ガイド)
- <summary>
- 認識子の説明
- 常に表示される唯一の要素
- 短く簡潔な英文が生成されるには、認識子のタイプ(プロパティ/メソッド/イベント/デリゲート etc...)に応じた適切な命名がされていなければならない
- <param> / <typeparam>
- <exception>
- 例外
- メソッドなどにマウスポイントした時のみに表示
「あれ？ <returns>は？」
と思った人は鋭い。
実は、戻り値はインテリセンスには表示されない。以下を見てほしい。
- DependencyObjectを渡すと、そのBindingExpressionがあれば取得するメソッド
- 引数に型情報が含まれてるから型情報を名前に含める必要はなく、currentという名前で十分
- 説明と戻り値の説明が一致しているので戻り値をインテリセンスに表示する必要性はない
- DependencyObjectを渡すと、その子孫のBindingExpressionがあれば列挙して取得するメソッド
- 引数に型情報が含まれてるから型情報を名前に含める必要はなく、子孫を列挙するのでparentという名前がシックリくる
- 説明と戻り値の説明が一致しているので戻り値をインテリセンスに表示する必要性はない
命名が正しければ確かに戻り値を表示する必要はないので、インテリセンスは<returns>の表示を省いている訳だ。
同じ事は、プロパティでも言えて、<value>は表示されない。
そんな人はいないと信じたいが、GetBindingExpression()が成功か否かをboolで返し、ref/outでBindingExpressionを返すようなことがあれば、それはメソッドシグネーチャが悪いということだ。
もちろん、例外はある。
- 結果の成否を返す操作
- IDisposableを返す操作
- LINQやそれを模倣した拡張メソッド
などが良い例だ。
ドキュメントコメントとオブジェクトブラウザ
オブジェクトブラウザは、簡易ヘルプとして使用することができて、インテリセンスでは表示されない<returns>や<remarks>も表示される。
もっとも、インテリセンスに表示されないからと言って、調子に乗って何行もダラダラと書いてはいけない。
理由は、XML Documentation形式のコンテンツはXMLであることにある。
XML Documentation形式のコメントを書いていて忘れがちだが、ドキュメントジェネレータによっては無視できない、最大のXMLならではの特徴は、
XMLでは、連続する空白文字(改行含む)は1文字のスペースに変換される
ということである。
そのため、XML Documentation形式のコメントを改行やインデントで整形するなど、以ての外でナンセンス極まりないことであることを肝に銘じておく必要がある。
よくありがちだが、
「取りあえずXML Documentation形式のコメントを付けて置いたら、そのうち誰かが・・・」
なんて甘い考えでいると、いざ立派なAPIリファレンスを作ってみたときに、ドキュメントジェネレータによっては、整形した筈のコメントの改行やインデントがきれいさっぱり取り除かれて、非常に残念なドキュメントが出来上がるなんてことになる。
この辺は、重々承知の上でコメント付けしなければならない。
さて、オブジェクトブラウザは、XMLファイルにエクスポートされたXML Documentationコメントを使用しているので、表示されるコメントは不要な空白文字がすべて圧縮された状態で表示される。
このため、オブジェクトブラウザで整形するためには、<para>や<list>を活用して、改行やリストも含めたコメントを記述する。
XMLの禁則文字とジェネリック
ジェネリックの括弧は、{}で代用可能。
その他については、使用しないで別の表記にすることは、難しいわけではないので、使用を避けることを検討したら良いかと思う。
DoxygenのMarkdownサポート
残念なことに、<para>や<list>は幅を取るのでソースファイル内でコメントが見にくくなるという問題がある。
オブジェクトブラウザは、目をつぶり、インテリセンスの表示とDoxygenの出力だけに絞るなら、<returns>や<remarks>でMarkdownを使用して整形するという方法もある。
Doxygenは直接ソースファイルからコメントを抽出するので、エクスポートされたXMLで空白文字が圧縮されても影響がない。
一方で、コメント中でプレーンテキストのように記述できるので、オブジェクトブラウザで表示したときは、改行等が取り除かれるとは言え、比較的読みやすく記述することが可能。
悪くない選択だ。
英文ドキュメントコメント生成時の注意事項
前回の記事のコミットに、日本語コメントが紛れていた。
しかし、私が入力したコメントではない。自動で入力されたものだ。
Atomineer Pro Documentationは、デフォルトでインテリセンスからベースクラスやインターフェースのコメントを取得できるときに、そのコメントを流用する。
当然、Visual Studioの言語設定が日本語設定で、日本語のドキュメントコメントが取得できる場合は、それを利用する。
では、この設定を切るのが良いのか？というと必ずしも正しくない。
というのも、実際のベースクラスやインターフェースのコメントとしてしっくりくるコメントが生成されるのが稀だからだ。
とすると、残った対策は、Visual Studioの言語設定を英語にすること。
これにより、メニューなどのUIで使用される言語設定が変わるだけではなく、.NET Framework SDKのXML Documentationのコメントの言語や、コードジェネレータで出力されるリソースファイル等のコメントの言語が変更される。
どちらを取るかは、正直悩ましい。
常時英語や、コメントを生成するときのみ英語にする方法もないわけではない。
