Readability — 読みやすいコードを書く

# この2つは、コンピュータにとって同じ意味
def p(o)
  o.tt = o.tt * 0.8
  o.save
end
 
def apply_premium_discount(order)
  order.total = order.total * 0.8
  order.save
end

# 読解時間の比較実験（チームで実施）
# 以下のコードを「理解する」のに何秒かかるか？
 
# テスト1（低可読性）
def c(u, p, d)
  t = p * (1 - d)
  u.bl -= t
  u.save
  Ac.new(u, t, 'p').save
end
 
# テスト2（高可読性）
def charge_user(user, price, discount_rate)
  charged_amount = price * (1 - discount_rate)
  user.balance -= charged_amount
  user.save
  AccountingRecord.new(user, charged_amount, 'payment').save
end
 
# 実際の計測結果
# テスト1: 平均23秒（しかも理解できたか確信が持てない）
# テスト2: 平均3秒（即座に理解できた）
# → 可読性改善で読解速度が7倍以上改善

# Before: 「何」を表す名前（型や構造を説明している）
x = Order.find(params[:id])
t = x.items.sum(&:price)
d = t * 0.1
r = t - d
 
# After: 「何のために」を表す名前（意図・役割を説明している）
order = Order.find(params[:id])
subtotal = order.items.sum(&:price)
discount_amount = subtotal * 0.1
final_price = subtotal - discount_amount

# 短すぎる（意味が失われる）
def calc(u, p)
  u.pt += p * 0.01
end
 
# 長すぎる（冗長で読み疲れる）
def calculate_and_add_loyalty_points_for_user_based_on_purchase_price(user_object, purchase_price_in_yen)
  user_object.total_loyalty_points += purchase_price_in_yen * 0.01
end
 
# ちょうど良い（意図が伝わり、冗長でない）
def add_loyalty_points(user, purchase_price)
  user.loyalty_points += (purchase_price * LOYALTY_RATE).floor
end

class OrderProcessor
  # インスタンス変数: クラス全体で使われるので詳細な名前
  def initialize(order, current_user)
    @order_being_processed = order
    @requesting_user = current_user
  end
 
  def call
    # ローカル変数: メソッド内だけなので短くても良い
    items = @order_being_processed.items
    total = items.sum(&:price)
    apply_discounts(total)
  end
end

# Before: 状態を表す名前（曖昧で質問と答えが混在）
premium = user.plan == 'premium'         # premiumは名詞か形容詞か？
expired = coupon.expired_at < Time.now  # ロジックが逆転している
active_user = user.active                # active_userか active?かわからない
 
# After: Yes/Noで答えられる質問形式（? で終わる）
class User < ApplicationRecord
  def premium?
    plan == 'premium'
  end
 
  def active?
    active && !locked?
  end
 
  def can_place_order?
    active? && !suspended? && verified_email?
  end
end
 
class Coupon < ApplicationRecord
  def expired?
    expired_at <= Time.current
  end
 
  def used?
    used_at.present?
  end
 
  def redeemable?
    !expired? && !used?
  end
end

# Before: 複数のものに単数形（混乱の元）
item = order.items           # itemsを受け取っているのにitem
data = []                    # dataは何のデータ？
result = User.where(active: true)  # resultも曖昧
 
# After: コレクションは複数形、意味のある名前
items = order.items
cart_items = []
active_users = User.where(active: true)
pending_orders = Order.where(status: :pending)

# イテレーションでも単数・複数を使い分ける
active_users.each do |user|      # users(複数) の中の user(単数)
  items.each do |item|           # items(複数) の中の item(単数)
    puts "#{user.name}: #{item.name}"
  end
end

# Before: 1つのメソッドがすべてをやる（30行、5つの責任）
def p(o, u, c)
  x = Order.find(o)
  if x.st == 1
    if u.pr == true
      x.tt = x.tt * 0.8
    end
    if c != nil
      cp = Coupon.find_by(cd: c)
      if cp && cp.ex > Time.now && cp.u == false
        x.tt = x.tt - cp.am
        cp.u = true
        cp.save
      end
    end
    x.st = 2
    x.save
    UserMailer.om(u.em, x.id).deliver_later
    return true
  else
    return false
  end
end

# After Step1: メソッド名と変数名を改善し、責任を分割
def process_order(order_id, user, coupon_code)
  order = Order.find(order_id)
  return false unless order.pending?  # ガード節で早期リターン
 
  apply_premium_discount(order, user)
  apply_coupon(order, coupon_code)
  complete_order(order, user)
  true
end

# After Step2: 各処理を独立したメソッドへ（各メソッドが1つのことだけをする）
 
# プレミアム割引を適用する（単一責任: 割引の適用だけ）
def apply_premium_discount(order, user)
  return unless user.premium?
 
  discount = (order.total * PREMIUM_DISCOUNT_RATE).round(2)
  order.total -= discount
  order.discount_amount = discount
end
 
# クーポンを適用する（単一責任: クーポンの適用だけ）
def apply_coupon(order, coupon_code)
  return if coupon_code.blank?
 
  coupon = Coupon.find_by(code: coupon_code)
  return unless coupon&.redeemable?
 
  order.total -= coupon.discount_amount
  coupon.mark_as_used!
end
 
# 注文を完了させる（単一責任: 完了処理だけ）
def complete_order(order, user)
  order.update!(status: :completed, completed_at: Time.current)
  OrderMailer.confirmation(user.email, order.id).deliver_later
end

# Before: 深い入れ子（右に行くほど読みにくい）
def process_refund(order, user)
  if order.completed?
    if order.refundable?
      if user.can_refund?
        # やっとここで本処理
        order.update!(status: :refunded)
        RefundMailer.notify(user, order).deliver_later
      end
    end
  end
end
 
# After: ガード節で早期リターン（入れ子が減り、本処理が際立つ）
def process_refund(order, user)
  return unless order.completed?
  return unless order.refundable?
  return unless user.can_refund?
 
  # 本処理だけが残る（視覚的にわかりやすい）
  order.update!(status: :refunded)
  RefundMailer.notify(user, order).deliver_later
end

# Before: コントローラに条件が散らばる（読むたびに条件を解釈する）
def index
  @orders = Order.where(status: 'pending')
                 .where('created_at > ?', 1.week.ago)
                 .order(created_at: :desc)
                 .limit(50)
end
 
def admin_index
  @orders = Order.where(status: 'pending')
                 .where('created_at > ?', 1.week.ago)
                 .order(created_at: :desc)
                 .limit(100)  # adminは100件
end
 
# After: スコープで意図を名前化する（条件を読む必要がない）
class Order < ApplicationRecord
  scope :pending, -> { where(status: 'pending') }
  scope :recent, -> { where('created_at > ?', 1.week.ago) }
  scope :newest_first, -> { order(created_at: :desc) }
end
 
def index
  @orders = Order.pending.recent.newest_first.limit(50)
end
 
def admin_index
  @orders = Order.pending.recent.newest_first.limit(100)
end

# Before: ビジネスルールがコントローラに漏れ出る
class OrdersController < ApplicationController
  def create
    # ビジネスルールがコントローラに書かれている
    if current_user.orders.where(status: 'completed').count >= 10 &&
       current_user.registered_at < 1.year.ago &&
       params[:order][:total] > 5000
      discount = params[:order][:total] * 0.05
    end
    # ...
  end
end
 
# After: ビジネスルールはモデルに閉じ込める
class User < ApplicationRecord
  LOYALTY_BONUS_THRESHOLD = 10
  LOYALTY_MEMBER_SINCE = 1.year
  LOYALTY_MINIMUM_ORDER = 5000
  LOYALTY_DISCOUNT_RATE = 0.05
 
  def eligible_for_loyalty_discount?(order_total)
    loyal_customer? && order_total >= LOYALTY_MINIMUM_ORDER
  end
 
  def loyalty_discount_for(order_total)
    return 0 unless eligible_for_loyalty_discount?(order_total)
    (order_total * LOYALTY_DISCOUNT_RATE).round(2)
  end
 
  private
 
  def loyal_customer?
    completed_orders.count >= LOYALTY_BONUS_THRESHOLD &&
      registered_at <= LOYALTY_MEMBER_SINCE.ago
  end
end
 
# コントローラはシンプルに
class OrdersController < ApplicationController
  def create
    discount = current_user.loyalty_discount_for(order_params[:total].to_i)
    # ...
  end
end

# Before: コールバックで副作用が隠れる（可読性を下げる）
class Order < ApplicationRecord
  after_save :send_notification
  after_save :update_inventory
  after_save :record_analytics
 
  private
 
  def send_notification
    # save を呼ぶだけでメールが飛ぶ——驚き（Surpriseの原則に違反）
    OrderMailer.status_changed(user, self).deliver_later if saved_change_to_status?
  end
 
  def update_inventory
    # save を呼ぶたびに在庫が変わる——テストで予測しにくい副作用
    items.each { |item| InventoryService.update(item) }
  end
end
 
# After: 明示的なサービスを使う（副作用が明示される）
class OrderCompletionService
  def call(order)
    ActiveRecord::Base.transaction do
      order.update!(status: :completed)
      notify_user(order)
      update_inventory(order)
      record_analytics(order)
    end
  end
 
  private
 
  def notify_user(order)
    OrderMailer.confirmation(order.user, order).deliver_later
  end
 
  def update_inventory(order)
    order.items.each { |item| InventoryService.decrease(item) }
  end
 
  def record_analytics(order)
    AnalyticsService.track('order.completed', order_id: order.id)
  end
end
 
# 使用側: 何が起きるかが明示的
OrderCompletionService.new.call(order)

# Bad: コードの繰り返し（What を説明——コードが読めれば不要）
# ユーザーを見つける
user = User.find(id)
 
# Bad: 廃れやすいコメント（コードが変わってもコメントが残る）
# 2023年3月1日 田中が追加: プレミアムユーザーへの割引
def apply_discount(user, order)
  # ...
end
 
# Good: なぜこの実装にしたかを説明（Why を説明——コードからは読み取れない）
# MySQLのロック競合を避けるためにfind_by(id:)ではなくfind()を使う
# SELECTにFOR UPDATE ロックが不要なケースではfindが高速
# 詳細: https://github.com/your-org/app/issues/1234
user = User.find(id)
 
# Good: ビジネスルールの背景を説明（なぜ30日なのか）
# 30日はキャンセルポリシー規約（Section 3.2）に基づく
# 変更時は legal@example.com に確認が必要
CANCELLABLE_PERIOD = 30.days
 
# Good: 非直感的な実装の理由を説明
# Rubyのfloat精度問題を避けるためにBigDecimalを使う
# 0.1 + 0.2 == 0.3 が false になる問題への対策
total = items.sum { |item| BigDecimal(item.price.to_s) }

# アンチパターン1: 否定の否定（二重否定）
unless !user.inactive?  # 赤: 頭が痛い
if user.active?         # 緑: ストレートに読める
 
# アンチパターン2: 三項演算子の乱用
result = condition1 ? (condition2 ? a : b) : (condition3 ? c : d)  # 赤
# ↓
if condition1
  result = condition2 ? a : b
else
  result = condition3 ? c : d
end  # 緑: 少し長いが読める
 
# アンチパターン3: 意味のない抽象（名前が具体的すぎず抽象的すぎる）
def handle(item)   # 赤: handleは何でもできる意味で何も言っていない
def process(data)  # 赤: processもdataも曖昧すぎる
 
def validate_cart_item(item)   # 緑: 何をするか明確
def calculate_shipping_fee(order)  # 緑: 何を計算するか明確
 
# アンチパターン4: 出力変数が不明確
def calculate(items, users, config)  # 赤: 何を返すかわからない
  # ...
end
 
def calculate_total_price(items, discount_config)  # 緑: 総価格を計算することが明確
  # ...
end

# 「思いやり」のあるコードとは
# 次の人（または3ヶ月後の自分）が読んだとき:
# - 変数名を解読する必要がない
# - 「これは何をするメソッドか」を推測する必要がない
# - 「この0.8は何だ？」と悩む必要がない
# - コードを頭の中でトレースしなくても流れがわかる
 
# そのために:
# 良い命名 = 解読作業をなくす
# メソッド分割 = 構造を見せる
# ガード節 = 条件を整理する
# スコープ = ビジネス意図を名前にする