Slide 1

Slide 1 text

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

Slide 2

Slide 2 text

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

Slide 3

Slide 3 text

サービス紹介

Slide 4

Slide 4 text

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

Slide 5

Slide 5 text

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

Slide 6

Slide 6 text

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

Slide 7

Slide 7 text

導入

Slide 8

Slide 8 text

Laravel 使ったことある人?

Slide 9

Slide 9 text

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

Slide 10

Slide 10 text

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

Slide 11

Slide 11 text

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

Slide 12

Slide 12 text

用語の整理

Slide 13

Slide 13 text

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

Slide 14

Slide 14 text

用語の整理(実運用の世界) /** * 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・・・ 構造要素

Slide 15

Slide 15 text

用語の整理(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) 概要 詳細 タグ

Slide 16

Slide 16 text

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

Slide 17

Slide 17 text

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

Slide 18

Slide 18 text

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

Slide 19

Slide 19 text

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

Slide 20

Slide 20 text

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

Slide 21

Slide 21 text

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

Slide 22

Slide 22 text

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

Slide 23

Slide 23 text

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

Slide 24

Slide 24 text

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

Slide 25

Slide 25 text

まとめ

Slide 26

Slide 26 text

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

Slide 27

Slide 27 text

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

Slide 28

Slide 28 text

補足

Slide 29

Slide 29 text

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

Slide 30

Slide 30 text

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

Slide 31

Slide 31 text

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

Slide 32

Slide 32 text

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

Slide 33

Slide 33 text

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

Slide 34

Slide 34 text

最近の傾向 ■ ここまで力説してきたが ■ 最近はドキュメンテーションコメントを書くよりも「コードを読め」の傾向にある ■ 後発の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) {