ドキュメントを残す目的とは？

チーム開発に必要なことです！

開発は複数人で、チームとして取り掛かります。
自分の書いたコードを、他メンバーが見た時に理解しやすいように、
自分が書いた関数や定数などの上にドキュメント（コメント）を書く必要があります。

どういう時に、どういうデータ型の引数を渡して、戻り値として何を返すのかなどです。

今回は、php、Laravel学習者向けに、他の開発者にもどういう意図で作られたファイル・関数なのかを

わかりやすく伝えるためのPHPDocの書き方をお示ししたいと思います。

PHPDocとは、PHPコード内にドキュメントブロック（「/** */」で括った箇所に記述したコメント）の中に記述する書式ツールのことです。

これにより、PHPコード内に含まれる関数、クラス、メソッドなどのドキュメントを作成することができます。

また、IDE（VScodeなど）の機能を利用し、メソッドなどにカーソルを合わせるだけで、そのメソッドの概要を表示させることができます。

具体的な書き方

PHPDocの書き方

上の画像は参考画像です。

1. ドキュメントブロックを作成する：PHPDocを作成する際一番初めに、関数やメソッドなどの要素の前にドキュメントブロックを作成します。

2. ブロック内のタグを使用する：ドキュメントブロック内に、関数、メソッド、クラスなどの説明や、パラメータ、戻り値、例外などのタグを追加します。

これらのタグは、@ を前に付けたキーワードで始まります。（@paramなど）

3. タグの詳細を記述する：タグには、必要に応じて説明を追加することができます。説明は、タグの後に続くテキストで表されます。

4. ファイル全体に関するドキュメントを作成する：クラスや関数だけでなく、ファイル全体のドキュメントも作成できます。

これは、ファイルの先頭にドキュメントブロックを追加することで行われます。

さいごに

PHPDocどんどん残していこう！

上記で示したタグは、ほかにもいろいろ種類がありますし、その時々のふさわしいデータ型書き方は異なってきます。

今回は、実際に現場で使用している基本的な書き方を紹介しただけなので、

より伝わりやすいPHPDocの書き方をご自身でいろいろ調査してみてください。

また、「doxygen」や「phpDocumentor」というツールを使用すれば、

詳細設計書としても使用可能なドキュメントを自動生成して、

設計書作成のコストを大幅に削減してるという便利な機能もあります。

さいごに、開発は複数人のチームプレーです。ゆえに、現場では他の開発者にわかりやすく伝えるということがとても重要です。

自分で作成した関数やメソッドには必ず、PHPDocやコメントで説明を記し、円滑に開発が進むようにしてください。