PHPのリーダブルコード（第一回）読みやすい関数が持つ、3つの特徴

PHPのリーダブルコード第一回です。次回はありません（気分屋）

まえがき

当記事はコードの書き方ではなく、理解しやすい関数のポイントや、定義の仕方を解説するものになります。

先に結論を言うと、内部の実装を見なくても処理が理解できる関数が良い関数です。

関数の機能にふさわしい名前をつけてあげるとグッドです。以下に例を挙げます。

これらの関数は名前を見ただけで処理が推測できます。

加えて、推測内容とジッサイの処理内容がほぼ同じです。

比較のために、私が今まで遭遇した名前から機能が想像できなかった関数も挙げておきましょう。

これらは一見して何の機能かわからない、もしくは別の機能をイメージさせる名前です。

こういった名前の付け方は避けましょう。

大丈夫です、ちゃんと機能にあった名前かどうかを考えれば、わかりやすい関数名がつけられるはずです。

※補足ですが、変数名や関数名に略語（account_name => anなど）を使うのは避けてください。

他人が見ても何の略語かわからない時がありますし、わかったとしても見るたびに脳内変換をかける必要があり、コードを読むコストが増します。

※名前をつけるときは、できるだけ動詞で始めてください。何をする関数なのかがすぐにわかります。

以下の関数を見てみましょう。

public function get_products($prd_obj) {
  $id = $prd_obj->id;
  $type = $prd_obj->product_type;
  // ...以下略
}

この get_products()関数では $prd_objという、おそらく商品に関するオブジェクトを渡していることはわかりますが、それがどう使用されているのかは内部を見るまで理解できません。

オブジェクトや配列は複数のデータを渡せて便利ですが、どんな情報を内部で使っているかを隠してしまうので、使いどころには注意してください。

もし配列を使う場合は、検索条件など、キーや値がコロコロ変わって安定しないものに限定しましょう。オブジェクトに関しては、どうしても必要な時を除いて避けるのが賢明でしょう。

読みやすい関数も合わせて書いておきます。

public function get_products($product_id, $product_type) {
  // ...以下略
}

このような引数の書き方であれば、IDとTypeから商品を取得してくるんだなと内部を見ることなく理解でき、実装を見る時間を節約できます。また脳のCPU使用率も下がるのでオトク感があります。

関数に適切なコメントをつけることで、すこし難しい機能でも理解が容易になり、実装を見る時間が減ります。

/**
 * 条件を元に、商品データを取得します。
 * @param  array $conditions
 * @return array
 */
public function get_by_conditions($conditions = []) {
    // 処理
}

関数やクラスの上に書かれている上記のようなコメントは、PHPDocとか phpDocumentorとか呼ばれてます。

これがあると、引数はどんな型なのか、どういう型で返ってくるのかが実装を見ることなく理解できます。

一緒に関数についての簡単な説明が書いてあると、よりわかりやすくなります。もっと言うとストレスが減ってやる気が出て良い気分を保ちやすくなります。

関数を作った場合はPHPDocをつけるようにしましょう。

また、メンテされていないPHPDocがあったら、ちゃんと実装に合うようにコメントを書き直しておきましょう。

※PHPDocの副次的効果として、引数に違う型のデータを指定したときにIDEが警告を出してくれるようになり、たいへん便利になります。あとPHPStormはPHP使いには必須アイテムだから、一度も使ったことない人は無料版をさわってみてほしい。

最初にも書きましたが、内部の実装を見なくても処理が理解できる関数が良い関数です。

みんなもわかりやすい関数を書いて、未来の自分やプロジェクトメンバーが頭を痛めないように頑張りましょい！