名付けについて色々調べたのでまとめる

初めに

エンジニア歴3ヶ月ほどの新人エンジニアです。Ruby・Railsで現在ほぼ自分だけで新規のサービス開発をしています。
自分が付けたメソッドやモデル名等を見直す機会があったので、これを機に特に意識せずに付けていた「名付け」について1から勉強したことをまとめていきます。

そもそもなぜ「名付け」は重要と言われているのか

「プログラミングで最も重要な技術の一つが名付け」と言われるくらい、プログラマーの間では名付けを重要視しています。
自分は今までなんで重要なのかが実感できていませんでした。

なぜ「名付け」は重要と言われているのか、答えはズバリ良いコードを書くためです。(当たり前)

良いコードの定義は色々あると思いますが、自分がしっくりきたのは

理解しやすくて、変更に強く読みやすいコード
WEB+DB PRESS Vol.110より

逆に「名付け」が悪いとどうなるか

良いコードの基準が自分の中で曖昧なので、「名付け」が悪いとどうなるのか調べました。

間違いが起こりやすい

例えばメソッド名がsaveなのに、実際の挙動がデータ削除だったら勘違いしますよね。

読みづらくて理解に時間がかかる

名前の内容自体はあっているけど直感で理解できないような単語を使っていたり、あまりにも名前が長すぎたりすると読みづらくて理解するのに時間がかかり、脳のメモリも消費します。

名前を変更する時間、コストがかかる。よって変更が難しくなる。

名前が悪いと良い名前に変更する必要が出てきます。変更したいメソッドがプロジェクトの至るところで使われていたりすると時間がめっちゃかかります。今の自分です。泣

じゃあ良い名前ってどんなのだ？

・名前から想像される動きと実際の挙動が一致している
・シンプルであること

色々調べた結果、この二つが良い名前の条件だと自分は思いました。
例えば記事で例えると、本文を読まなくてもタイトルで本文の内容が理解できる。つまり本文(コード)を過不足なくシンプルに要約したタイトルが良い名前ということです。

自分的には、この考えがしっくりきました。

自分のコードを見直して多かった悪い名前のパターン

自分の名付けを見返してみると、悪い名前のパターンが見つかりました。それが下記３つです。

・名前から想像される動きが実際の挙動の一部しか言い表していない
・名前から想像される動きが抽象的すぎる
・名前の英語の意味が実際の挙動と乖離している

名前から想像される動きが実際の挙動の一部しか言い表していない例

before
→下記は記事の掲載日を今日より前にしようとした場合にエラーが出るようにするためのカスタムバリデーションのメソッドです。

article.rb

def before_today
  errors.add(:published_start_at, 'Please set today or after today') if published_start_at.nil? || published_start_at < Date.today
  errors.add(:published_end_at, 'Please set today or after today') if published_end_at.nil? || published_end_at < Date.today
  errors.add(:published_start_at, '掲載開始日より終了日が早くなっています') if published_end_at < published_start_at
end

after
→メソッドの中に、掲載開始日が終了日よりも前に設定しようとした場合に発生する処理もまとめて入れてしまっていました。なので、メソッドを２つに分けました。

article.rb

def before_today
  errors.add(:published_start_at, 'Please set today or after today') if published_start_at.nil? || published_start_at < Date.today
  errors.add(:published_end_at, 'Please set today or after today') if published_end_at.nil? || published_end_at < Date.today
end

def between_start_and_end
  errors.add(:published_start_at, '掲載開始日より終了日が早くなっています') if published_end_at < published_start_at
end

名前から想像される動きが抽象的すぎる

before

users_controller.rb

after
→管理者用の処理をまとめるコントローラーにしたかったのに、userという抽象的すぎる名前にしていたので直しました。

administrators_controller.rb

名前の英語の意味が実際の挙動と乖離している

before
→ユーザーのステータスの表示を英語から日本語にするヘルパーメソッドです

users_helper.rb

def admin_user_status_conversion(client)
    case client.status
    when "TEMP" then
      content_tag :span, "仮登録", class: "label label-primary"
    when "WAITING_FOR_APPROVE" then
      content_tag :span, "承認待ち", class: "label label-warning"
    when "REGISTERED" then
      content_tag :span, "登録完了", class: "label label-success"
    when "REJECTED" then
      content_tag :span, "登録取消", class: "label"
    else
      "例外"
    end
  end

after
→conversionという単語は変換することを意味するので、翻訳という意味のtranslationにしました。

users_helper.rb

def admin_user_status_translation_english_to_japanese(client)
    case client.status
    when "TEMP" then
      content_tag :span, "仮登録", class: "label label-primary"
    when "WAITING_FOR_APPROVE" then
      content_tag :span, "承認待ち", class: "label label-warning"
    when "REGISTERED" then
      content_tag :span, "登録完了", class: "label label-success"
    when "REJECTED" then
      content_tag :span, "登録取消", class: "label"
    else
      "例外"
    end
  end

参考文献

・WEB+DB PRESS Vol.110
→「名前付け大全」という特集がとても参考になりました！
・プログラミングでよく使う英単語のまとめ【随時更新】
・クラスの命名のアンチパターン
・モデルやメソッドに名前を付けるときは英語の品詞に気をつけよう
・Naming -名前付け-