C#の便利機能ドキュメントコメントを使ってスムーズに開発しよう

Unityで使っているプログラミング言語のC#には「ドキュメントコメント」という便利な機能があります。これはメソッド名やクラス名などのコメント対象の前に特別なコメントフィールドを用意してXML要素を配置することで、説明を表示できるものです。

例えば<summary>タグを使うと、メソッドなどの説明をXMLで保持することができます。IDEでは以下のようにメソッド名にカーソルを合わせたときに説明を表示してくれます。(私がよく使っているIDEはVSCodeですが、Visual Studioでも同じように表示してくれます)

これがあると、メソッドの中身を見に行かなくてもその場でどんなメソッドなのかを知ることができるので、開発をスムーズに進めることができます。

ドキュメントコメントは開発中のサポートに加えて、開発後にHTMLのAPIドキュメントを生成することもできます。ブラウザからクラス間の継承関係やインタフェースの実装状況を確認することもできるので、しばらく時間が空いてから再びゲームのアップデートする場合などにも便利です。

ソースコードだけ見て処理の意図が分かるのがベストですが、人間に分かりやすい言葉で書かれた説明があればもっと意図を汲み取りやすくなります。通常のコメント文に加えて、ドキュメントコメントも使いこなせるようになると気遣いのできる開発者になれます。

コメント文の大切さについては以下の記事で解説しています。コメント文がなかったことで出くわした悲劇についても涙と共に語っています。

エクスプラボ

ゲーム開発のプログラミングではコメント文で意図を伝えよう

https://ekulabo.com/leave-comments-in-code

「なんでこの処理を入れたのか」という意図が分かるようにしておくのは、円滑にプロジェクトを進める上で大切です。あなたひとりで進めているプロジェクトであっても、1週間前のソースコードは別人が書いたものに感じますからね。

ドキュメントコメントの使い方

ドキュメントコメントはクラス名、メソッド名、フィールド名の前に「///(トリプルスラッシュ)」を付けてその中にXMLのタグを書いていきます。

例えば以下のようなイメージです。

<summary>は対象のクラス名やメソッド名の要約した説明を記載できるタグで、IDEでもこの説明を表示することができます。開発中にも恩恵を得られるタグなので、このタグだけでも使えるようになると良いでしょう。

私の場合はフィールドの説明については通常のコメント文で済ませてしまうことが多いですが、別のプロジェクトでスクリプトを使いまわしたい場合はつけることもあります。

クラス名やメソッド名については大体付けています。最初はちょっとめんどくさいと思っていましたが、マウスカーソルを合わせたときにホバーウィンドウで説明が表示された時の感動があったので今では自然と書くようになっています。

ドキュメントコメントの概要についてはMicrosot社のサイトもご参照ください。

docs.microsoft.com

 

1 Pocket

XML ドキュメント コメント - C# プログラミング ガイド

https://docs.microsoft.com/ja-jp/dotnet/csharp/programming-guide/xmldoc/

よく使うドキュメントコメントのタグ

個人的によく使うドキュメントコメントのタグを紹介します。こちらもMicrosoft社のサイトで公開されているタグを参照しながらご覧ください。

docs.microsoft.com

 

20 Users

12 Pockets

ドキュメント コメント用の推奨タグ - C# プログラミング ガイド

https://docs.microsoft.com/ja-jp/dotnet/csharp/programming-guide/xmldoc/recommended-tags-for-documentation-comments

summaryタグ

上でも触れたタグです。名前の通りクラス、メソッド、フィールド要約を記載できます。例えばメソッドの振る舞いを人間に分かる言葉で書いておけば、メソッドの中身を見に行かなくても内容を把握することができます。

IDEではこの<summary>タグで書かれた内容をホバーウィンドウで表示してくれるのが嬉しい点。

上でも書きましたが、<summary>タグだけでも使えるようになっておくと開発に役立ちます。特に自分だけでなく他の人もいるプロジェクトであれば、他の人が書いたメソッドの中身をすぐに把握できるのは嬉しいですからね。

振る舞いや戻り値などの説明もここに書いてしまっています。

後々HTMLなどのAPIドキュメントとしてまとめるなら戻り値は<returns>タグを使って記載しておくと良いでしょう。

paramタグ

メソッドの引数について説明を記載することができます。<param>の開始タグの中にnameで引数の名前を指定します。説明文は</param>の終了タグとの間に記載します。

複数の引数がある場合は、<param>の行を複数用意することでそれぞれ説明を記載することができます。

こちらもIDEのインテリセンスで表示してくれるので便利です。呼び出し元で確認するというよりは、対象のメソッドで引数の説明を残しておくイメージです。

typeparamタグ

こちらは型パラメータの説明を記載します。以下の例では任意の型の配列を生成していますが、メソッド内で使われる型に指定がある場合はこのタグを使って説明しておくと丁寧です。

メソッド名の横に書かれている<T>の部分にマウスカーソルを合わせると、<typeparam>に記載した説明を表示してくれます。

初心者の頃は<T>と書かれているジェネリックの表記が分からなかったのですが、GetComponent<AudioSource>()とかList<GameObject>などの型名を表している部分のことです。型名も動的に渡せるのは便利ですね。

APIドキュメントの生成

開発中の便利さの他に、開発後にスクリプト全体の関係やpublicなメソッドの使い方を文章として確認するためにもドキュメントコメントが使われます。

こうしたHTMLを作成してくれるツールには「DocFX」や「Doxygen」があります。「DocFX」はMicrosoft社のツールなので使いやすいかもしれません。そう言いながら私は慣れている「Doxygen」を使っちゃってますが。

プロジェクトが完成した後、あるいはプロジェクトの途中であってもドキュメントを生成しておいて、全体を確認するのに使えます。継承関係を表示してくれるのがありがたいので、定期的にドキュメントを出力するのも良いと思います。

まとめ

C#の便利機能ドキュメントコメントの紹介でした。インテリセンスで説明を表示してくれるタグだけでも使えるようになると、開発のサポートとして役に立ちます。

コメント文を残しておくのは大切なので、ドキュメントコメントについても使っていきましょう。