ドキュメンテーション コメント再入門 2023/12/20 第159回 PHP勉強会@東京

自己紹介 ■ 名前: ちひろ ■ X: @chiroruxxxx ■ 会社: 株式会社モリサワ

サービス紹介

目標 ■ これを撲滅したい！ /** * @param array $input * @return bool */ public function doSomething(array $input): bool

話さないこと ■ 型の話はしません！！

目次 ■ 導入 ■ 用語の整理 ■ ドキュメンテーションコメントとは ■ まとめ ■ 補足

導入

Laravel 使ったことある人？

Eloquent(Model) のsaveメソッド使ったことある人？

saveメソッドの 返り値わかる人？

Model::save() /** * Save the model to the database. * * @param array $options * @return bool */ public function save(array $options = []) ヒント︓「保存が成功したか」ではない

用語の整理

用語の整理(PHPの世界) // inline comment /* * multiple lines comment */ /** * doc comment? */ class Something 単⼀⾏⽤コメント 複数⾏⽤コメント ドキュメントコメント ReflectionClass::getDocComment() T_DOC_COMMENT

用語の整理(実運用の世界) /** * Sets a list of trusted host patterns. * * You should only list the hosts you manage using regexs. * * @param array $hostPatterns A list of trusted host patterns */ public static function setTrustedHosts(array $hostPatterns) DocBlock ドキュメンテーション コメント • PHPDoc • JavaDoc • JSDoc • etc・・・ 構造要素

用語の整理(PHPDocの世界) /** * Sets a list of trusted host patterns. * * You should only list the hosts you manage using regexs. * * @param array $hostPatterns A list of trusted host patterns */ public static function setTrustedHosts(array $hostPatterns) 概要 詳細 タグ

PHPDocとは ■ phpDocumentor – 一番普及したPHPDoc ■ PSR-5, PSR-19 – phpDocumentorから脱却した標準をつくりたい ■ Psalm – phpDocumentor, PSR-5の型をサポート ■ PHPStan – T_DOC_COMMENTで取れるもの

ドキュメンテーションコメントとは

ドキュメンテーションコメントとは ■ エンジニアは数百、数千のメソッドや関数の中から 適切なものを選んで使用する必要がある ■ そのすべてのメソッドのコードを読んで理解していられるほどの時間的余裕は 無い ■ ドキュメンテーションコメントは書き手が適切なメソッドを素早く選択できるように メソッドの説明を提供する自己文書化の技法 ■ ドキュメンテーションコメントを活用することで ライタブル(Writable)なコードを実現できる ■ 自己文書化をすることで、仕様と実装の距離が近くなり、結果として 参照がしやすく、変更に追従しやすくなる

コードを読まずに見える範囲

ドキュメンテーションコメントに何を書 くべきか ■ メソッドを利用する人が知りたい内容を書く ■ メソッドの概要 ■ メソッドの詳細な説明 ■ パラメータや返り値などの情報 – 型自体はPHP側で制約をかけられることが多い – 型よりもその値についての説明を書くほうが価値が高い ■ 最初のsaveメソッドの例

期待と責務 /** * divide は第1引数を第2引数で割った値を返す。 * * 第2引数は0以外でなければいけない。 */ function divide(float $a, float $b): float

副作用 /** * walk は各要素にコールバックを適⽤する。 * * このメソッドはクラス内で保持している配列を変更する。 */ public function walk(callable $callback): self

計算量 /** * crossJoin は引数のコレクションとの直積を返す。 * * このメソッドは計算量がO(n^3)のため、データ量が多い場合には使⽤を推奨しない。 */ public function crossJoin(self $another): self

メモリ使用量 /** * outputCSV は配列をCSV形式に変換する。 * * 変換結果をすべてメモリ上で保持するため、使⽤する際にはデータ量に注意するべし。 */ function outputCSV(array $data): string

まとめ

目標(再掲) ■ これを撲滅したい！ /** * @param array $input * @return bool */ public function doSomething(array $input): bool

まとめ ■ ドキュメンテーションコメントはエンジニアが適切なメソッドを選択するために書く ■ 以下のような内容を書くと良い – 期待と責務 – 副作用 – 計算量 – メモリ使用量

補足

わかりやすい命名をすればドキュメン テーションコメント要らないのでは？ ■ そもそも目的が違う ■ 命名はリーダブルなコードを実現する – コードの読み手にわかりやすい命名にする – その要素の特徴を簡潔に書く ■ ドキュメンテーションコメントはライタブルなコードを実現する – コードの書き手にわかりやすいドキュメントにする – その要素について詳細に書く

StringBuilder ■ Javaで文字列を結合する際に使用される – 状況によるが、結合演算子を使用するよりもメモリ消費を抑えられる ■ 読み手からするとこれはStringBuilderで良い ■ 書き手からするとStringBuilderの命名だけでは情報が足りない – 結合演算子との違いがわからないため

StringBuilder /** * A mutable sequence of characters. (以下略) */ public final class StringBuilder

仕様はテストに書けばいいのでは？ ■ 実装と仕様の距離が遠くなる – 仕様を知るために毎回大冒険 するのか？ ■ テストコードと母国語、どちらが読 むのがはやいか？

ドキュメンテーションコメントは 嘘をつく？ ■ 人間と機械と両方が読み手のもので発生する – つまり、メソッド名や変数名も同じリスクを持っている – ドキュメンテーションコメントも、メソッド名や変数名と同じように注意し コードレビューすれば良い ■ ドキュメンテーションコメントファースト 1. シグネチャとドキュメンテーションコメントを書く 2. テストを書く 3. 実装を書く 4. リファクタリングする

最近の傾向 ■ ここまで力説してきたが ■ 最近はドキュメンテーションコメントを書くよりも「コードを読め」の傾向にある ■ 後発のGoの例 – atEOF とは？ // ScanWords is a split function for a Scanner that returns each // space-separated word of text, with surrounding spaces deleted. It will // never return an empty string. The definition of space is set by // unicode.IsSpace. func ScanWords(data []byte, atEOF bool) (advance int, token []byte, err error) {