ruby-coder

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Ruby Coder

Ruby 编码规范

Ruby 3.x Modern Syntax

Ruby 3.x 现代语法

Use hash shorthand when keys match variable names:

ruby

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

For general naming conventions, semantic methods, and enumerable patterns, see

references/ruby-style-conventions.md

当键名与变量名匹配时，使用哈希简写：

ruby

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

关于通用命名规范、语义化方法和枚举模式，请参阅

references/ruby-style-conventions.md

。

Sandi Metz's 4 Rules for Developers

Sandi Metz 的开发者四条规则

These rules enforce strict limits to maintain code quality. Breaking them requires explicit justification.

这些规则通过严格限制来保障代码质量。若要打破规则，必须提供明确的理由。

Rule 1: Classes Can Be No Longer Than 100 Lines

规则1：类代码行数不得超过100行

Limit: Maximum 100 lines of code per class

Check: When a class exceeds this limit, extract secondary concerns to new classes

ruby

undefined

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

检查方式：当类超出此限制时，将次要功能提取到新类中

ruby

undefined

When exceeding 100 lines, extract secondary concerns:

当代码行数超过100行时，提取次要功能：

class UserProfilePresenter # Presentation logic class UserProfileValidator # Validation logic class UserProfileNotifier # Notification logic


**Exceptions**: Valid Single Responsibility Principle (SRP) justification required

class UserProfilePresenter # 展示逻辑 class UserProfileValidator # 验证逻辑 class UserProfileNotifier # 通知逻辑


**例外情况**：需要符合单一职责原则（SRP）的明确理由

Rule 2: Methods Can Be No Longer Than 5 Lines

规则2：方法代码行数不得超过5行

Limit: Maximum 5 lines per method. Each if/else branch counts as lines.

ruby

undefined

限制：每个方法最多5行代码，每个if/else分支都算作一行。

ruby

undefined

Good - 5 lines or fewer

良好示例 - 5行或更少

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


**Exceptions**: Pair approval required (Rule 0: break rules with agreement)

ndef 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：经协商可打破规则）

Rule 3: Pass No More Than 4 Parameters

规则3：方法参数不得超过4个

Limit: Maximum 4 parameters per method. Use parameter objects or hashes when more data is needed.

ruby

undefined

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

ruby

undefined

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


**Exceptions**: Rails view helpers like `link_to` or `form_for` are exempt

def create_post(post_params) Post.create(user: post_params.user, title: post_params.title, content: post_params.content) end


**例外情况**：Rails视图助手（如`link_to`或`form_for`）不受此限制

Rule 4: Controllers May Instantiate Only One Object

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

Limit: Controllers should instantiate only one object; other objects come through that via facade pattern.

ruby

undefined

限制：控制器应仅实例化一个对象；其他对象通过外观模式（facade pattern）从该对象获取。

ruby

undefined

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


- Prefix unused instance variables with underscore: `@_calculation`
- Avoid direct collaborator access in views: `@user.profile.avatar` -> use facade method

class DashboardController < ApplicationController def show @user = current_user @posts = @user.posts.recent @notifications = @user.notifications.unread end end


- 未使用的实例变量以下划线开头：`@_calculation`
- 避免在视图中直接访问嵌套关联对象：`@user.profile.avatar` -> 使用外观方法

Code Quality Standards

代码质量标准

Thread Safety

线程安全

Use

Mutex

for shared mutable state:

ruby

class Configuration
  @instance_mutex = Mutex.new

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

对于共享可变状态，使用

Mutex

：

ruby

class Configuration
  @instance_mutex = Mutex.new

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

Idempotent Operations

幂等操作

Design operations to be safely repeatable:

ruby

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

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

ruby

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

Refactoring Triggers

重构触发条件

Extract classes when:

Class exceeds 100 lines (Sandi Metz Rule 1)
Class has multiple responsibilities
Class name contains "And" or "Or"

Extract methods when:

Method exceeds 5 lines (Sandi Metz Rule 2)
Conditional logic is complex
Code has nested loops or conditionals
Comments explain what code does (code should be self-explanatory)

Use parameter objects when:

Methods require more than 4 parameters (Sandi Metz Rule 3)
Related parameters are always passed together
Parameter list is growing over time

Create facades when:

Controllers need multiple objects (Sandi Metz Rule 4)
Views access nested collaborators
Complex data aggregation is needed

提取类的场景：

类代码行数超过100行（Sandi Metz规则1）
类承担多个职责
类名称包含“And”或“Or”

提取方法的场景：

方法代码行数超过5行（Sandi Metz规则2）
条件逻辑复杂
代码包含嵌套循环或条件
注释用于解释代码功能（代码应具备自解释性）

使用参数对象的场景：

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

创建外观类的场景：

控制器需要多个对象（Sandi Metz规则4）
视图访问嵌套关联对象
需要进行复杂的数据聚合

When to Break Rules

何时可以打破规则

Sandi Metz's "Rule 0": Break any of the 4 rules only with pair approval or clear justification.

Rule	Valid Exception
100 lines	Clear SRP justification required
5 lines	Complex but irreducible algorithms
4 params	Rails view helpers exempt
1 object	Simple views without facades

Document all exceptions with clear reasoning in code comments.

Sandi Metz的“规则0”：只有在获得配对开发人员批准或有明确理由时，才能打破这四条规则中的任意一条。

规则	有效例外情况
100行限制	需要符合单一职责原则的明确理由
5行限制	复杂但无法简化的算法
4个参数限制	Rails视图助手不受限制
1个对象限制	无需外观模式的简单视图

所有例外情况都需要在代码注释中记录清晰的理由。

References

参考资料

```
references/sandi-metz.md
```
- Code smells, refactoring, testing principles
```
references/ruby-tips.md
```
- Type conversion, hash patterns, proc composition, refinements
```
references/ruby-style-conventions.md
```
- Naming, semantic methods, enumerables, composition

```
references/sandi-metz.md
```
- 代码坏味道、重构、测试原则
```
references/ruby-tips.md
```
- 类型转换、哈希模式、Proc组合、refinements
```
references/ruby-style-conventions.md
```
- 命名规范、语义化方法、枚举、组合