なうびるどいんぐ

脳みそ常時-3dB

[VisualStudio]C++でもXMLドキュメントコメントを自動挿入したい！！

      2018/04/07    HimaJyun

黒魔術C++、難読奇怪な言葉遣いで驚異的な速度を叩き出す闇の魔術で、一度その魅力に取り憑かれるともう二度と抜け出せないんだとか……

そのC++ですが、VisualStudioで組んでいるとC#のXMLドキュメントコメント(一部の人の為に言い換えるとJavaDocやDoxygen)と同じ物が使えます。

ただ、VisualStudio 2015 Communityの段階ではなぜかそれを自動で挿入する機能はないみたいなので、今回はこれを自動で挿入出来る様にしてみようと思います。(将来的に出来るようになったりするのかなぁ……)

スポンサーリンク

ドキュメントコメント

結論から言ってしまえば、拡張機能を入れる事なのですが、それだけではつまらないので色々オマケ解説もしましょう。

正式名称が良く分からないので、ここではこの様なコメントを全てまとめて「ドキュメントコメント」と呼ぶ事にしましょう。

C++でもXMLドキュメントコメント

例えば、C#(と言うよりVisualStudio?)では以下の様なXML形式のコメントを記入する事によってドキュメントコメントを利用出来ます。

/// <summary>
/// ほげぇ！！
/// </summary>
/// <param name="str">文字列(はぁと</param>
/// <returns>数値(すぅぱぁはぁと</returns>
private int hoge(String str) {
    return 114514;
}

これを入れておくと、関数名にマウスカーソルを重ねた際に説明が表示され、関数呼び出しの際に引数の説明が表示されます。
visualstudio-cpp-xml-document-001

要は「/」を3つ入れる訳ですね、C#では///と入力した時点で自動的に<summary>や<param>が対象のメソッドに合わせて追加されます。

そして、この機能自体はC++でも利用できるのですが、「///」を入力した際の自動挿入には対応しておらず、手で<summary>なんて打ち込む必要がある。(C#を広めたいM$の意図的な物ではないかと勘ぐってしまう)

拡張機能で対処する

こう言う時、2013から追加されたCommunity版であれば拡張機能が利用出来る。(前までは有料版が必要だった)

探してみた所「Cpp Triple Slash」と言う文字通りの拡張機能で出来るみたい。

と言う訳で「ツール」->「拡張機能と更新プログラム」へと進む
visualstudio-cpp-xml-document-002

いつもどおり拡張機能を追加する、「Cpp Triple Slash」とでも検索しよう。

きっと出て来るであろうから、それを選択してダウンロード、インストールする。
visualstudio-cpp-xml-document-003

使い方

もはや解説の必要すらない。

単に「///」を入れるだけ、編集用にコメント部にIntelliSenseが使える様にもなっている。

/// <summary>
/// ほげぇ！！
/// </summary>
/// <param name="str">文字列(はぁと</param>
/// <returns>数値(すぅぱぁはぁと</returns>
int hoge(std::string str) {
    return 114514;
}

「///」をタイプしてコメントさえ入れてしまえば、後はカーソルを重ねたりした時の表示や関数を呼び出す時の引数の説明なんかもそのまま利用出来る。

むしろなぜ自動挿入が標準の機能として提供されていないのかが分からない限り、MSさん……

個人的にはJavaDocの「/**」より「///」の方がキーから手を離さなくて済むので好きですね。(US配列だとまた違うのかも知れませんが)

コメントいろは

とは言え、これだけでは流石に内容が白湯よりも薄いので、このドキュメントコメントのいろは……ちょっとだけ教えちゃう。

XMLを出力する

プロジェクトの構成プロパティから「C++->出力ファイル->XMLドキュメントファイルの生成」を「はい(/doc)」にする事で、ソースコード内のXMLドキュメントコメントをXMLとして出力することが出来ます。
visualstudio-cpp-xml-document-004

上手く扱えば(そう言うソフトを用意すれば)自動で公開用のMarkdownやらドキュメントを生産する事も出来るでしょう。

改行したい

JavaDocとかでも良くあることなんですけど、コメント内での改行はひと工夫必要。

普通に改行しただけではダメ。

/// <summary>
/// ほげぇ！！
/// ふがぁ！！
/// </summary>
/// <param name="str">文字列(はぁと</param>
/// <returns>数値(すぅぱぁはぁと</returns>
int hoge(std::string str) {
    return 114514;
}

ちなみに<br />とか付けて無理やり改行しようとしても無駄、それが出来たらXSSっぽい事が可能になってしまうから？

改行したい時は<para>を使う。

/// <summary>
/// <para>ほげぇ！！</para>
/// <para>ふがぁ！！</para>
/// </summary>
/// <param name="str">文字列(はぁと</param>
/// <returns>数値(すぅぱぁはぁと</returns>
int hoge(std::string str) {
    return 114514;
}

<para>は<param>とかでも使える。(名前がややこしいな)

/// <summary>
/// <para>ほげぇ！！</para>
/// <para>ふがぁ！！</para>
/// </summary>
/// <param name="str">
/// <para>もじれつぅ！！</para>
/// <para>すとりんぐぅ！！</para>
/// </param>
/// <returns>数値(すぅぱぁはぁと</returns>
int hoge(std::string str) {
    return 114514;
}

見た目はJavaDocで<br>とか書き込むより綺麗だしすき。CppTripleSlashはドキュメントコメントでIntelliSenseが使えるので入力もラクチン。

(そもそも複数行に及ぶような説明が必要な神関数を作るなって話なんだけど)

ドキュメントコメントの必要性

これは意見が分かれる所、ドキュメント(というかコメント)は必要か否か。先に言っておくと私は「状況によっては必要だが必須ではない」。

私は「そもそもコメントが必要な時点で関数や変数のネーミングが悪い、機能が多すぎる」、延いては「良いネーミングのソースコードにコメントは不要」みたいな考えです。

ソースコードというのは所詮は機械への指示を人が分かりやすく表すための「表現」にしか過ぎないのです、つまりはソースコード自体が既に「文章」でもあるのです。

ソースコードを読めば分かるような事をわざわざコメントに記す必要はないでしょう。そういう意味で、getTime()関数に「// 時間を取得します」というコメントを付けるのは不適切(過剰説明、とでも言うべき？)です。

で、getTime()だと「いつの時間を取得するのか？」が分からないわけで、それをコメントで「// 今の時間を取得します」とするのは不適切です。正しくは関数を「getNowTime()」のような名前に変えるべきなのです。

ね？「getNowTime()」ならコメントなどなくとも呼び出すとどういう事が起こるのか分かるでしょう？

先程までは「ソースコードを上手く書けない」場合の話、では、逆に「コメントを上手く書けない場合」はどうか？実はこれも本質は同じ。

「これをコメントで分かりやすく表現出来ない」と言うのであれば、それは表現が不適切という訳で、その「不適切な表現」はコメントだけでなくソースコードも含まれます。

「簡潔に説明出来ない関数」では「簡潔に説明出来ない処理」を行っているという訳であり、それは「多機能すぎる」という事でもあるでしょう。

「1つの関数で実行するのは一言で説明出来る範囲内」をポリシーにしたい所。

ただ、それはそれとして、「他者に使わせることを大前提とした部分」、すなわち公開されたAPIに関しては必ずコメントを付けるべきでしょう。

APIというのは「中で何が行われているか知る必要がない」状態にするべきであって、そのためには適切な関数名はもちろんの事、どういうパラメータが必要か、どういう値が返ってくるのか、というコメントは必要だと考えています。

……なんて立派な事言ってるけど、私自身言うほどキチンと出来ないけどね

 - プログラミング ,