🔦

PHPDocを使う

2022/08/22に公開

PHP

document

tech

PHPDoc

PHPに用意されてる特別仕様のコメントって感じ。

色々できて引数@param、戻り値@returnとかの型とか書けるので静的型付け言語っぽく書けるようになる。IDEでの補完機能が型や変数名が出るようになり実装中も役立つ。

例）配列の中身を足して合計を返す関数を作った時

array.php

/**
* 引数の配列の中身（int）を足して、合計を返す
* @param array<int> intのみの配列を許容する
* @return null|int $sum 数値のみの配列の合計値を返す
*/
function sumArray($array)
{
    // 不正な入力を受け付けない
    if (!is_array($array) || empty($array)) return null;
    if (isIntArray($array) === false) return null;
    
    // 足す
    $sum = 0;
    foreach($array as $numeric_value) {
        $sum += $numeric_value;
    }

    echo "合計は {$sum} です。" . PHP_EOL;
    return $sum;
}

/**
* 配列の中身がintかどうか返す
* $parame array<mixed> 何かしらの配列
* $return bool 配列の全要素がintの時true
*/
function isIntArray($array)
{
    $bool_array = array_map('is_int', $array);
    // 全要素がintでtrue
    if (in_array(true, $bool_array, true)) {
        return true;
    } else {
        return false;
    }
}

例えばこんな感じで関数の場合、何が引数で、何を返すかが分かる。そのため、今後そのコードを用いる人は使い方を間違えにくくなる。（という願望。）

privateメソッドとかは特にこれ書いた方がいいと思う。なぜなら、これが仕様書の代わりになるし、privateメソッドはそのスコープ内でしか使えないので、コードとドキュメントの距離が近い方が理解しやすい、と思う。。。※個人的感想

もし、PHPDoc内に書ききれない内容や経緯などがあればドキュメントのリンクをPHPDoc内に書いてしまえばいいと思う。

php-doc-link.php

/**
* こんな感じでリンクが貼れる
* @link https://sample.com/documentation 詳細仕様書のリンク
*/

PHPDocを使う

PHPDoc

参考ページ

Discussion