PHP
コメント
PHP5
PHP7
健康

PHP7以上を使うならメソッドコメントほぼいらないんじゃねぇ?という疑問

php7におけるメソッドコメントについて

以前、以下のような投稿をした。

PHPのコメントって何を書けばいいの?という人に役立つtips

上記内容は基本的にphp5を対象にしたものでしたが、最近業務でphp7を利用するようになってから

「あれ?メソッドコメントほぼいらないんじゃね?」というような気がしてきたのでメモしておく。

php5での書き方

簡単な例を挙げる。

定数でスタッフIDを持つのは云々は置いといてほしい。

<?php
/**
 * クラスの説明
 *
 * @link チケットかバックログかなんかのURL
 */
class Staff
{
    const STAFF_IDS = [
        10,
        20,
        30
    ];

    public function __construct()
    {
    }

    /**
     * スタッフIDかどうかの判定
     * @param int $id
     * @return bool
     */
    public function isStaff($id)
    {
        return in_array($id, self::STAFF_IDS, true);
    }
}

php5代では(順次拡張されていったが)タイプヒンティングが貧弱で、基本的にスカラー型に対応していなかった。それに加え、戻り値の型宣言もできなかった。

そのためメソッドコメントに引数と戻り値の型を書いておくという努力でPHPエンジニア達はメソッドの読みやすさをフォローしていたわけである。

php7以降での書き方

しかし、php7からはスカラー型宣言、戻り値の型宣言共に対応された。

上に例示したクラスをそれに習って書くと以下のようになる。

<?php
/**
 * クラスの説明
 *
 * @link チケットかバックログかなんかのURL
 */
class Staff
{
    const STAFF_IDS = [
        10,
        20,
        30
    ];

    public function __construct()
    {
    }

    /**
     * スタッフIDかどうかの判定
     */
    public function isStaff(int $id): bool
    {
        return in_array($id, self::STAFF_IDS, true); // 引数型宣言でintに固定されているので第3引数のtrueもいらないかも
    }
}

こうなってくると、メソッドコメントのparamやreturnが必要になる場合というのがあまり想像できなくなってくる。

書く必要があるのは処理の概要とthrowsくらいなのではないかというのが最近の私なりの結論。

余談ではあるが、ファイルコメントのlinkも改修の度に追加されるとノイズになる可能性もあり、削ってもいいような気がしている。コミットログを綺麗にしておけばそんなに必要ないような。