PHPerによる引数命名の極意

引数の極意

メソッド名、引数をみて何をやっているか分からないメソッドはストレス値が上がりますよね。
メソッド名について語られていることは多いのですが、引数についてはあまり語られていないので、
分かりやすい引数について考えて書いてみました。

このメソッドの引数を極意に合わせて修正して行きます。

class Repository {
    public function method($name1, $name2, $address, $amount, $color, $perPage)
}

引数は左から、店舗名、商品名、お店の住所、商品の値段、商品カラー、1ページの表示数とします。
引数をもとにデータを絞り込み取得したデータを返却するメソッドをイメージしてください。
メソッド名は簡略化のため適当です。

Level.1 曖昧さを減らし明確な名前をつけるべし

引数を定義する上で大切なのは、メソッドを使う人がどこに何を送ればいいか迷子にならないことです。
Docとかに書くのもいいですが、まずは変数名を明確にしましょう！

以下のよう、曖昧さを減らし明確にしましょう。

店舗名：　$shopName
商品名：　$itemName

今回は、google翻訳ですぐ出るような名前にしましたが、チームで共通認識になっている言葉を使うのが一番いいかなと思います！
僕がいるチームでは商品はproductsテーブルにあるので、商品に関する変数名は$product〇〇で共通化しています。

public function method($shopName, $itemName, $address, $amount, $color, $perPage)

少しはいい引数になりましたね！

Level.2 型を宣言すべし

物によっては文字列じゃなくて、数値でデータを管理しているパターンもあるでしょう。
ちょっと無理矢理ですが今回は、$colorが文字列ではなく数値でデータを管理しているとします。

1: 赤
2: 青
3: 緑

こうした時に業務上の知識を細かく把握してる人じゃないと、$colorに文字列を送るのか数値を送るのか、判断が難しくなってしまいます。
小さな不明確事項はストレスの原因です。
それを防ぐために、引数に型の定義をしてあげます。

public function method(string $shopName, string $itemName, string $address,
                       int $amount, int $color, int $perPage)

これでどういう値を送ればいいかさらに明確になりましたね！
DDDなど利用してる場合は、値オブジェクトで型を宣言するとさらに良くなると思います。

Level.3 意味でまとめるべし

業務知識がある人が見るとわかるのですが、今の引数の状態だとどの引数が検索条件なのかがちょっと曖昧です。
なので、うまくグループ分けをしてどれが検索条件かわかるようにしましょう。
私の理想パターンだとDTOなど検索用パラメータを保持できるオブジェクトを作成して引数にするパターンです。

class ParameterDto {
    private string $shopName;
    private string $itemName;
    private string $address;
    private int $amount;
    private int $color;
}

class Repository {
    public function method(ParameterDto $parameter, int $perPage)
}

LIKE検索するのであれば変数名にlikeをつける、大小の比較を実施するならgtやltをつけるなどプライベート変数名を工夫するともっと分かりやすくなるかなと思います。

DTOなんてうちのチームでは導入できないよー。という場合はまとめずにLevel.2の状態のままが良いかなと思います。

public function method(array $parameter, int $perPage)

配列にしてしまうと検索できる条件が不明確になるのであまり良くないかなと。。。
ただ検索条件がかなり増えて引数が7つ以上になるとかの場合は、配列にした方がコードが読みやすいかなと思います。

あとがき的な

引数の極意といいいつつ、分かりやすい変数名つけた方がいいよの話になってしまいましたね。
次も極意シリーズとして描けるようにがんばります。