PHP-BLT #8 でPHPDocについて発表しました。

Conference php

PHP-BLTにいってきました

8/8にあったPHP-BLT #8 で「PHPDocのおさらい」というタイトルで発表しました。

内容としては「PHPDocで関数とかの仕様書けるよ！」という当たり前すぎる話を5分に引き伸ばした感じです。 ただこの話は、自分の中で悶々と溜めてたことなので、話せてよかったなーと思います。

今回は初めてのLTということで、事前にスライド見ながら練習とかしてみたんですけど、やっぱり5分は短いですね。
色々話したかったけど時間で話せないこともあったので、ここで発散しておきます。

PHPDocをなぜ書くのか

今回の発表では、「コードレベルの仕様を書きたいから」というのを理由にしてますし、私自身もそれが一番の理由だと思っています。

ですが、「静的解析したいから」という理由の人が一定数います。

もちろん私もPhpStorm大好き人間なので静的解析には大変にお世話になっていますし、静的解析のためのPHPDocも書くことはあります。( @var とか)
ですが、それはあくまで副次的な利点であり、本質は違うんじゃないかなと思います。

やはりPHPDocの源流はJavaDocだと思いっています。 Javaは型ガッチリな言語なので、JavaDocの発展に静的解析はあまり関係していないと思うんですよね。(総称型とかは置いといて)
それと同じように、PHPDocの本来の目的も、静的解析ではなくもっと別のところにあるのかなと思います。

今回はそれを「仕様を書きたいから」というところに着地させています。

仕様は命名からわかるべき

「仕様を書かなくてもわかるようなクラス・メソッド名や関数名にするべき」という意見をよくききます。
リーダブルコードにも書いてある内容ですよね。

もちろんそれはそうなのですが、理想と現実は違うのかなと感じています。
というのも、

  • そんなに英語できる人が少ない(語彙や前置詞の使い方など)
  • 2,3ワードでほんとに仕様を説明できるの?

みたいな問題があるのかなと。

あとは、フレームワークの制約上難しい場合もありますよね。
例えばYii1系だと、 beforeAction というメソッドがあり、名前のとおり各アクションを実行する前に実行されます。
このメソッドを利用する時に、このメソッドの仕様を命名で解決できるかというと、無理ですよね。(どのタイミングで実行されるかは明白だけど、何をするのかはわからない)

もちろん命名が不要なわけではないです。
概要を命名で説明して、細かい仕様をPHPDocで説明するくらいの温度感がいいのかなと思います。

PHP-BLT楽しかった！

ちなみに私以外で発表していた人は「よく勉強会やカンファレンスで喋ってるあの人」みたいな人ばっかりでした。
そして内容も難しい話ばっかりでした。みんな凄いなー。
でも知らないことを知ったり、自分と違う環境の人と話すことはとても楽しいですよね。
また次も参加したいなー。

今回は体調不良だったので、次回は体調良好な状態でいきたい！