ruby-coder

Ruby 编码

Ruby 3.x 现代语法

当键名与变量名一致时，使用哈希简写：

age = 49
name = "David"
user = { name:, age: }

有关常见命名约定、语义化方法和可枚举模式，请参阅 references/ruby-style-conventions.md。

Sandi Metz 面向开发者的 4 条规则

这些规则设定了严格限制，以维护代码质量。违反规则必须给出明确的理由。

规则 1：类不超过 100 行

限制：每个类最多 100 行代码

检查：类超出此限制时，将次要职责提取到新类中

# When exceeding 100 lines, extract secondary concerns:
class UserProfilePresenter  # Presentation logic
class UserProfileValidator  # Validation logic
class UserProfileNotifier   # Notification logic

例外：必须提供符合单一职责原则（SRP）的理由

规则 2：方法不超过 5 行

限制：每个方法最多 5 行。每个 if/else 分支都计为一行。

# Good - 5 lines or fewer
def process_order
  validate_order
  calculate_totals
  apply_discounts
  finalize_payment
end

# Avoid - extract when too long
def process_order
  return unless items.any?
  return unless valid_address?
  self.subtotal = items.sum(&:price)
  self.tax = subtotal * tax_rate
  self.total = subtotal + tax
  charge_customer
  send_confirmation
end

例外：需要结对审批（规则 0：经双方同意后方可违反规则）

规则 3：参数不超过 4 个

限制：每个方法最多 4 个参数。需要传入更多数据时，使用参数对象或哈希。

# Parameter object when data is related
def create_post(post_params)
  Post.create(user: post_params.user, title: post_params.title, content: post_params.content)
end

例外：link_to 或 form_for 等 Rails 视图辅助方法不受此限制

规则 4：控制器只能实例化一个对象

限制：控制器应只实例化一个对象；其他对象通过该对象以外观模式提供。

# Good - single object via facade
class DashboardController < ApplicationController
  def show
    @dashboard = DashboardFacade.new(current_user)
  end
end

# Avoid - multiple instance variables
class DashboardController < ApplicationController
  def show
    @user = current_user
    @posts = @user.posts.recent
    @notifications = @user.notifications.unread
  end
end

• 为未使用的实例变量添加下划线前缀：@_calculation
• 避免在视图中直接访问协作者：@user.profile.avatar -> 改用外观方法

代码质量标准

线程安全

使用 Mutex 保护共享的可变状态：

class Configuration
  @instance_mutex = Mutex.new

  def self.instance
    return @instance if @instance
    @instance_mutex.synchronize { @instance ||= new }
  end
end

幂等操作

设计可安全重复执行的操作：

def activate_user
  return if user.active?
  user.update(active: true)
  send_activation_email unless email_sent?
end

重构触发条件

在以下情况下提取类：

• 类超过 100 行（Sandi Metz 规则 1）
• 类有多个职责
• 类名包含“And”或“Or”

在以下情况下提取方法：

• 方法超过 5 行（Sandi Metz 规则 2）
• 条件逻辑复杂
• 代码中有嵌套循环或条件语句
• 注释解释代码的作用（代码应当能够自我说明）

在以下情况下使用参数对象：

• 方法需要超过 4 个参数（Sandi Metz 规则 3）
• 相关参数总是一起传递
• 参数列表不断变长

在以下情况下创建外观：

• 控制器需要多个对象（Sandi Metz 规则 4）
• 视图访问嵌套的协作者
• 需要聚合复杂数据

何时违反规则

Sandi Metz 的“规则 0”：只有获得结对审批或有明确理由时，才能违反 4 条规则中的任何一条。

规则	有效例外
100 行	必须有明确的 SRP 理由
5 行	复杂但无法进一步拆分的算法
4 个参数	Rails 视图辅助方法不受限制
1 个对象	不使用外观的简单视图

在代码注释中清楚说明所有例外的理由。

参考资料

• references/sandi-metz.md - 代码异味、重构、测试原则
• references/ruby-tips.md - 类型转换、哈希模式、proc 组合、refinements
• references/ruby-style-conventions.md - 命名、语义化方法、可枚举对象、组合