こんにちは、株式会社エヌ・エイ・シー システムインテグレーション事業部です。
今回はPHPのドキュメンテーションコメントについてご紹介いたします。
ドキュメンテーションコメント（ドキュメントコメント）とは、クラスや関数等の部品の説明を記載できるコメントです。
特定のルールに沿って書くことで、対象の機能、引数、戻り値などが一目でわかるようになります。
また、コマンドを実行してコメントの内容を自動でドキュメント化したり静的解析に利用することなどもできます。
通常のコメントよりも必要な情報を整理しやすく、保守性を意識できるのが特徴です。
こちらの記事ではPHPの書き方で説明していきますが、JavaやC#など他の言語にも同様の機能があります。
ドキュメンテーションコメントは決められた記法があり、説明対象の直前（ファイルの場合はファイルの先頭）に「/**..*/」のように書く必要があります。
また、タグ（「@…」）を使ってドキュメント化する情報を意味付けすることもできます。
以下、主に使われるタグです。
| タグ | 概要 | 記述方法 |
| @author | 作者 | @author 名前やメールアドレス |
| @version | バージョン情報 | @version 現在のバージョン |
| @param | 引数 | @param 型 変数名 説明 |
| @return | 戻り値 | @return 型 説明 |
| @throws | 例外 | @throws 例外名 説明 |
| @see | 参照 | @see 関連メソッドなど |
では、実際にドキュメンテーションコメントの例を見てみましょう。
基本的には、機能の簡易説明、詳細説明、タグの順で記述し、管理したい情報をまとめます。
主に以下の内容を記載。
主に以下の内容を記載。
上記を記載したクラス名や関数名にVSCode 上でマウスカーソルをあてると…
このように、クラスや関数の説明が表示されます。
またコメント無しの場合、以下の様に表示されます。
なんとなく推測できないこともないですが、やはりコメントの内容が補足してある方が分かりやすいと思います。
特に、複雑な処理の場合は読み解くにも時間がかかるため、できればパッと見て理解できる状態にしておきたいですね。
簡単にご紹介させていただきましたが、いかがでしたでしょうか。
規模の大きい開発や保守運用期間の長いプロジェクトこそ、ドキュメンテーションコメントを記載し、メンテナンスをしやすい形に整えていくことが大切だと思います。
