弊社で毎月開催し、PHPエンジニアの間で好評いただいているPHP TechCafe。
2022年7月のイベントでは「PHPDoc」について語り合いました。
弊社のメンバーが事前にまとめてきたPHPDocの情報にしたがって、他の参加者に意見を頂いて語り合いながら学びました。
今回はその内容についてレポートします。
rakus.connpass.com
- そもそもPHPDocとは何か
- PHPDocに関する質問
- まとめ
- 編集後記
そもそもPHPDocとは何か
PHPDocについては、2021年5月に一度 【PHPDocについて語り合う】と題して、PHPTechCafeが開催されており、 その時のページを基におさらいをしました。 rakus.connpass.com
PHPDocとは、関数、定数、クラス、メソッド、プロパティなどにブロックの説明として残すコメントのことです。
基本的にはただのコメントなのでプログラミングに影響はありませんが、一部のツールではPHPDocの内容によって処理を行うものもあります。
ただPHP8.0でアトリビュートが追加されたので、PHPDocとしての記述もアトリビュート方式の記述へどんどん変わっていくのではないかというのが前回の見解でした。
活用するポイント
- 編集者の理解が捗る
- IDEで補完が効きやすくなる
- 静的解析がより正確に実行できる
- 実行時に型チェックされる
等が挙げられます
課題
明確な記述ルールは決まっていないというのが結構ネックです。
色々な書き方がありますが、 "PHPドキュメントジェネレータであるphpDocumentorの記述がデファクトスタンダードなのか" とか、"PhpStormにあるようなものを採用すればいいのではないか" とか、色々な意見があります。
そのような点を標準化するべく、PSR-5やPSR-19で議論が行われています。
今のところまだドラフト中ではありますが、PSR-5ではPHPDocのことが書いてあります。
コメントとして
- 「静的解析ツールでそれぞれ独自にやりたい方法でやっている感じがします。」
- 「PHPDocはPhpStormで生成されるものを書いているだけです」
というようなものをいただきました。 IDEで使えるものを使うという方もおられる印象です。
代表的な書き方
基本的なタグで、よく使うものをピックアップしています。
基本的なタグ
@から始まる文字列。何についてのドキュメントかを示す。
- @param：関数またはメソッドの引数について記述
- @return：返り値について記述
- @throws：例外について記述
- @var：変数について記述
- @todo：開発でやるべきことがあることを示す
型の記述
前述の タグ の後に記述することで、対象の型を記述する
例
@return int 整数を返す
- リテラル型
- int, bool, string etc...
- 配列型
- ただの配列（中身不明）： array
- 数値キーの配列： int
- 複数の型があり得る配列： (int|string)
- 文字列キーの配列： array<string, int>
- キーごとに値の型が異なる配列： array{id: int, name: string}
その他の書き方
false型
- booleanではなくfalse型
property
__get(),__set()を使った動的なプロパティを記述することが可能
ローカル変数の型指定
- @var で指定
このようなことを記入しておくと、IDEで補完が効いたり静的解析でチェックされるというメリットがあります。
基本的なものは上記のとおりですが、型の記述ではBoolean型ではなくfalse型があったり、__get(),__set()を使った動的なプロパティを作れるpropertyなどがあります。
このfalse型などの変わったものについては まとめページ に書いてあるので、目を通していただければと思います。
この中でいただいたコメントでは、
- 「個人開発ではめっちゃ@todo使います。これを書いているとPhpStormとかでコミットする時に「まだTODO残ってるよ」って教えてくれますね。」
- 「@varは変数とかよりはpropertyのためのものだと思ってもらった方がいい。PHPStan対応で必要な場合を除いてあまり書かずに済ませたいですね。」
さらに興味深いところでは
というものをいただきました。
これについては、
- 「その発想はなかった！」
- 「嫌だそれ。アノテーションにプログレスとか書いて、このクラスどこまで出来上がったみたいな、そこから自動的にガントチャートに進捗率が反映されるって。中々ですね。」
- 「「@progress 70%」とか世知辛いですね～、どうせこれ人が書いているから99%とかで止まっているんでしょうね。」
というような、いかにも業界な感想で話が盛り上がりました。
PHPDocに関する質問
今回は ”そもそもPHPDocってどういう時に使うか” という点を念頭に議論が行われました。
最低限書いておきたいコメント
必須
- @var
- @param
- @return
- @throws（明示的にthrowしているなら）
@var,@param,@returnに関しては、ソース上型を書けば十分という意見もあります。@throwsは何かあった時にツールが補完してくれるということも考えられます。
「@returnや@paramはArrayの時だけかな」というコメントもいただきましたが、
これについては、（Arrayの）中身ということで考えれば、記載があった方が良いと思われます。
ただ、変なArrayになるのであれば、クラスで返す事などを考えて、Arrayを受け取らなければならないシーンを無くしていきたいと思います。
他にも
- 「型宣言と同じものをPHPDocに書き写さなくて良い」
- 「記載不要と思っていてもPhpStormがコメントを入れるよう求めてくる」
というコメントをいただきました。
こちらについては、型宣言しているのなら二重メンテになるので記載不要と思われますが、PhpStormは入れるよう警告してきますので「そこまで補完しなくてもいいのでは？」という意見もあがりました。
微妙
- @use/@used-by
- @package
@use/@used-byは、可変の関数を使ったときに、”ここで使っています” と、示すために使うものです。 ですが、@use/@used-by で説明しなければいけないようなロジック自体をできるだけ避ける方が望ましいと思われます。
@package は、名前空間の対応物または補足として使用できます。
要素を異なる階層でグループ化できる論理的な細分化を提供できます。
その他
- 「参考となる物が存在する場合は @link を使う場合があります」
というコメントをいただきました。 コードのコメントとしては、”意味があるものは書くべき” と思いますので、@linkの記述はあると便利です。
また、ここまでの話から、
というコメントがありました。
そうなるとPHPDocのコメントを書かなくてよくなることも考えられそうですが、
半面、
- 「「言語組み込みジェネリクスはいらない」という考え方もあり、実行時それまでやってしまうと重くなり、そこはPHPDocで収めておくのがいいんじゃないか 」
- 「パフォーマンスに影響するなら考えものですね。PHPDocで良い気がする」
というコメントもありました。
phpDocumentor使ってますか？
- PHPプロジェクトのドキュメントを自動で作成してくれるツール
- 基本的なPHPDocコメントだけでも作成してくれうのでかなり有効
- CIに組み込めばドキュメントのメンテナンスコストも削減できると考えられる
と紹介されました。 phpDocumentorを使うことによってプロジェクトのドキュメントを自動で作成してくれますので、 基本的にはPHPDocコメントが書かれていれば、人によっては見やすいドキュメントを生成します。
Documentationのサイトでは、出力されるドキュメントのイメージを確認できます。
右側にあるSearch検索ボックスにクラス名などを入力するとクラス一覧が表示されます。
それをクリックすると説明が表示されます。
このページ のTable of ContentsにPと書いてあり鍵マークが外れているものがpublic、鍵が付いているものがprivate、Mがmethod、interfaceはIとなっています。
PHPDocの記載がすべて出力されるか
主催者側で検証したところ、PHPDocで型を書いているところは全部出力してくれたようです。
プロダクトではまだ使っていませんが、試しに実行してみたところしっかり出力してくれたようです。
ドキュメントのメンテナンスコストが減り、CIに組み込めば開発コストも下げられる期待があります。
phpDocumentorの使いどころは？
PhpStormを使っている場合、調べたいものがあればShift+Ctrlで調べられたりします。
詰まるところ ”みんながコード読める環境ならphpDocumentorによるドキュメントは無くても良い” ということなのでしょうか。
使いどころを考えてみます。
PHP TechCafeメンバーの中で出た意見
- 「受託開発で一部機能だけ作ってくれという案件で納品する時にあると良いのかな」
- 「APIのドキュメントであれば、内部実装よりは「何を受けて何を返すのか」が最低限分かればいいので、簡単にチェックできるものがあれば良いのかな」
という意見があったことが紹介されました。
参加者の方からは、
- 「ライブラリにはあってほしい」
というコメントをいただきました。 ライブラリ内部までは不要ですが、どう使ったら良いかはわかると嬉しいと思います。
- 「ライブラリも基本的にソースを読んじゃうから、別にドキュメントいらない説」
- 「英語を読むよりソースコードのほうが読みやすくないですか？」 そんなコメントもいただきました。
これについてはPHP TechCafeのメンバーの中では、”PhpStormで検索すればだいたい賄えるのでは”とも話が挙がっていました。
phpDocumentorで出力されるもの
PHPDocで型定義をしていない変数については、phpDocumentorは出力してくれるのでしょうか？
この疑問については、以下の結果が紹介されました。
- PHPDocに書いていなくてもコードで定義されている型が反映される
- 引数なども反映される
- PHPDocを書いていれば、関数の説明などのコメントも反映される
WEB APIに関しての使いどころ
WEB APIの仕様をコメントの中に記述していくことが考えられますが、ここからWEB APIに関して話が盛り上がります。
Swagger などはその場で実行できるので便利ですが、APIのドキュメントとなると意識的に最新化し続けないといけないという意見が挙がりました。
WEB APIがドキュメント化されていても、PHPに慣れている人からすると ”ソース読めばよいのでは” という考えも出てきます。
とはいえ、ざっくりと概要を知りたい人にはドキュメントがあったほうが助かるかもしれません。
PHPDocの記述だけで WEB APIの動作確認をする方法はないか
PHPDocの記述の中に、APIの仕様を記載しておくだけでAPIの動作を試すようなことはできないのでしょうか。 実際にそのようなものがOSSに存在しているのでしょうか。 参加者の方が、見つけてくださいました。
APIドキュメントを書いておいて、フロントエンドとバックエンドを疎結合にする開発
先にOpenAPIを使ってAPI仕様を決めておけば、バックエンドとフロントエンドを分けて開発する事ができそうですが、 PHPDocの記載にによってAPI仕様を定義するのであれば、先にバックエンド側のコードの方にAPI仕様を書くことになるため、バックエンドとフロントエンドを同時に分けて開発することは難しいと思われます。
他にも以下のような意見が寄せられました。
- Swaggerを使う場合、別環境を準備しなければいけない為、個人開発でミニマムに済ませたいときはPHPDocに書いたほうが楽なのではないか。
- PHPDocはコメントとしての力が強いので、自由に書けるというのがメリット
戻り値がvoidの場合、”@return void”は書いたほうが良いか？
- 「書かないとPHPStanで怒られる。」
というコメントをいただきました。
- 「 わざわざそこまで書くのか？」
- 「言語の方で補えるものは書かなくても良くなってきているかもしれないです。」
という話もありましたが、voidを書くのが圧倒的多数のようでした。
@throws\Throwableは書くべき？
これは「書きたい」という意見が多かったようです。 言語仕様のほうで引数の型や戻り値の型は表現できますが、@throws\Throwableの方はしっかり書いといたほうが良さそうです。
- 「PhpStormでWarningが出るときと出ない時がある。 」
- 「CatchしているときはThrowsを書かないと警告」
- 「逆に投げているのにCatchしていないとそれも警告」
というコメントもいただきました。
各IDEでサポートしているPHPDocの範囲が分からない
PhpStormの提言として、PHPDocにどこまで対応しているかというリストはないようです。 公式の記載である程度情報がまとまっているようですが、特にどこまで対応しているという記載はありません。
PhpStormが公開しない理由があるのでしょうか。
- 「勢いよく増えていくから、書いているうちに古くなるから。」
- 「メンテナンスのコストがかかるんでしょうか。 」
- 「結局PSRの議論がクローズしないのも、こういうことがあるからなのでしょうか。 」
という意見がありました（実態は不明のようです）。
レガシーシステムとPHPDocの向き合い方
レガシーなシステムをメンテナンスする際のPHPDocの扱い方についての議論が行われました。
PHPDocはあくまでもコメントですので、型エラーになるわけでもありません。そのため、レガシーなシステムにもPHPDocを書いていくほうが良いのではないかという考えが紹介されました。
どうしてもレガシーなところでコードを直接触るのをためらうときには、PHPDocコメントを書いて解析に委ねるのも戦略の一つです。
レガシーな記述方法で言えば、その一つに、array shapes1 がありますが、素直にコメントを書いていくとすれば大変です。 リファクタリングによりクラスに置き換えることできることを考えると、PHPDocの記述で補完するよりはリファクタリングすることを優先したほうが良いように思います。
他の言語のDocコメントとの違いは？
参加者から以下のような意見がありました。
PHPDocも、前述の通り、 ”これは必ず書かないといけない” という決まったルールはまだありませんが、それは他の言語でも同様のようです。
とは言え、 ”これくらいは記載したいよね” という緩いルールのような共通認識はあるようです。
まとめ
- 「考えていることがみんな似ていてホッとする」
- 「PHPDocを深く考えたことがなかったので勉強になりました」
というコメントをいただきました。
明確なルールがない部分もありますが、参加者同士で疑問を共有して考えを知れたので良い機会となりました。
主催者も含めて、この機会に勉強することができたようです。
編集後記
以上、PHPerのための「PHPDoc相談会」として、PHPDocについて深く掘り下げていきました。 PHPで書くコメントは開発者が普段から当然のように利用しているものですので、主催者/参加者ともに非常に盛り上がりを見せていました。 今後もPHPに関することや、新たなニュースに着目していきたいと思います！
「PHP TechCafe」では今後もPHPに関する様々なテーマのイベントを企画していきます。 皆さまのご参加をお待ちしております。
- PHPDocの配列表記方法の一つ。キーごとに値の型が異なる配列等を表現する。↩
