Upgrade to Pro — share decks privately, control downloads, hide ads and more …

ドキュメンテーションコメント再入門

chiroruxx
December 20, 2023

 ドキュメンテーションコメント再入門

第159回PHP勉強会@東京で発表した内容です。

chiroruxx

December 20, 2023
Tweet

More Decks by chiroruxx

Other Decks in Technology

Transcript

  1. 目標 ▪ これを撲滅したい! /** * @param array $input * @return

    bool */ public function doSomething(array $input): bool
  2. Model::save() /** * Save the model to the database. *

    * @param array $options * @return bool */ public function save(array $options = []) ヒント︓「保存が成功したか」ではない
  3. 用語の整理(PHPの世界) // inline comment /* * multiple lines comment */

    /** * doc comment? */ class Something 単⼀⾏⽤コメント 複数⾏⽤コメント ドキュメントコメント ReflectionClass::getDocComment() T_DOC_COMMENT
  4. 用語の整理(実運用の世界) /** * 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・・・ 構造要素
  5. 用語の整理(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) 概要 詳細 タグ
  6. PHPDocとは ▪ phpDocumentor – 一番普及したPHPDoc ▪ PSR-5, PSR-19 – phpDocumentorから脱却した標準をつくりたい

    ▪ Psalm – phpDocumentor, PSR-5の型をサポート ▪ PHPStan – T_DOC_COMMENTで取れるもの
  7. ドキュメンテーションコメントに何を書 くべきか ▪ メソッドを利用する人が知りたい内容を書く ▪ メソッドの概要 ▪ メソッドの詳細な説明 ▪ パラメータや返り値などの情報

    – 型自体はPHP側で制約をかけられることが多い – 型よりもその値についての説明を書くほうが価値が高い ▪ 最初のsaveメソッドの例
  8. 目標(再掲) ▪ これを撲滅したい! /** * @param array $input * @return

    bool */ public function doSomething(array $input): bool
  9. わかりやすい命名をすればドキュメン テーションコメント要らないのでは? ▪ そもそも目的が違う ▪ 命名はリーダブルなコードを実現する – コードの読み手にわかりやすい命名にする – その要素の特徴を簡潔に書く

    ▪ ドキュメンテーションコメントはライタブルなコードを実現する – コードの書き手にわかりやすいドキュメントにする – その要素について詳細に書く
  10. 最近の傾向 ▪ ここまで力説してきたが ▪ 最近はドキュメンテーションコメントを書くよりも「コードを読め」の傾向にある ▪ 後発の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) {