大阪電気通信大学Vtuberプロジェクトの活動や、映像制作に関するニュースを発信しています。
お久しぶりです、しょうごです。
チームでの活動が増えてくると、やはりコミュニケーションが大切だと身にしみて感じますよね！
特にプログラミングなどをしていると、同じ制作チームの仲間たちだけでなく、過去の自分や未来の自分ともコミュニケーションを取らないといけません。
「めんどくさい！わかってくれ！」
そう思ったことは100回や200回の話ではないでしょう。
命名規則の統一や、複数名で制作するときにどこがどうなっているかわからない、せめてわかりやすいドキュメントでもあったらいいのに！
そういうあなたのために、今回はdoxygen形式のコメントの書き方を紹介していきます。これがあれば、VSCodeを使用しているときにわかりやすくなるほか、ツールを導入さえすればUnityで作成中のプログラムのドキュメントを作成したりしてわかりやすく可視化することができます！
※記事中に添付されているプログラムは、先日公開した「電ch!VTuberおみくじ-unityroom版-」を作る際に使用したスクリプトから引用しています。良かったら遊んでね「遊ぶ方はこちらから」
1.基本的なコメントの書き方
これまで書いてきた基本的なプログラミングのコメントの書き方としてはこんな感じ
「 // ~~ 」と後ろにいろいろと記載したり、「 /* ~~ */ 」と数行を囲ったりしますね。
前者は1行で説明したいとき、後者はプログラム自体をコメント化しプログラミングとして動かなくしたいときに使います。
ただ、これだけだと後から呼んだ時によくわからなくなったり、記載規則がバラバラになってしまったり、、、
そんな時にdoxygen形式のコメントを使用してみましょう！
2.doxygen形式でのコメントの書き方
- ファイルの冒頭につけるコメント
各プログラムファイルの冒頭に記載するコメントになります。
@file ファイル名
@brief 簡潔な説明
@author 作成者の名前
@date 作成日（もしくは最終更新日）
@details 詳細説明
@note 補足説明
- クラスや関数の直前につけるコメント
各関数の前に記載する内容になります。
Unityを使い始めたころだとあまり書くことはないかも？
@class クラス名
@fn 関数名
@brief 簡単な説明
@param (引数名) 引数の説明
@return 戻り値の説明
@detail 詳細な説明
- 変数へのコメント
これまでの「//」でも普段使いでは特段問題はありません。
ですが、doxygen形式では変数へコメントする際は直前に
//! 変数へのコメント
と記載をします。
この方法でコメントしたものはドキュメント化されますが、それ以外はドキュメントされません。全部ドキュメント化されると困ることもあると思います。そういう時には使い分けができるのです。
とはいえ、例の画像のような「何をしているのかを記載したコード」というのはよく目にします。
ですが、よほど複雑ではない限り、コードを読めばすぐにわかります。なので、こういったコメントは手間なので書かないほうが良いと思います。（私はね！）
ただ、わかっているダメな点や、どうしてこのような実装をしたのかなどの理由はしっかりと記載しておきましょう。
3.doxygen形式のメリット
では、改めてプログラミングのコメントをdoxygen形式で記載するメリットについて触れていきます。
1.記載ルールをわかりやすく統一化でき、見やすい
2.ツールを使用して、使用しているスクリプトをドキュメントとしてまとめることができる
3.htmlで出力し、クラス等の管理が容易になる
以上3点が、メリットとしてあります。
複数人で作業する際や、かなり多くのスクリプトファイルを扱う際はdoxygen形式を用いているとかなり便利にできます。
ということで、今回はプログラミングのコメント手法の一つであるdoxygen形式の紹介でした。
個人的にはこれを使うと結構便利で、最初は面倒に感じつつも、最近はこの方法で「コメントを作成→doxygenを使用してhtmlに書き出し」をしています。
やったことが無い人は、試してみても良いかも？
