Ruby 代码规范与风格指南

代码布局

缩进

在Ruby中，建议使用2个空格进行缩进。这与许多其他流行语言（如Python）的推荐缩进风格一致，能够保持代码的清晰与一致性。避免使用制表符（tab），因为不同编辑器对制表符的显示宽度可能不同，会导致代码在不同环境下布局混乱。

def some_method
  # 这里使用2个空格缩进
  puts "Hello, Ruby!"
end

行长度

尽量保持每行代码不超过80个字符。这有助于提高代码的可读性，特别是在多人协作开发和在较小屏幕（如笔记本电脑）上查看代码时。如果一行代码确实过长，可以考虑将其拆分成多行。例如，在方法调用中，当参数较多时：

result = some_complex_method(
  long_argument_1,
  long_argument_2,
  long_argument_3
)

在链式方法调用中，也可以适当拆分：

data = [1, 2, 3]
  .map { |num| num * 2 }
  .select { |num| num > 3 }

空行

合理使用空行可以增强代码的可读性。在不同功能块之间，例如不同的方法定义之间，使用一个空行进行分隔：

def method_one
  # 方法一的代码
end

def method_two
  # 方法二的代码
end

在类的定义中，不同属性或方法组之间也可以使用空行分隔：

class MyClass
  # 类属性相关代码

  def method_related_to_attributes
    # 代码
  end

  # 业务逻辑方法

  def business_logic_method
    # 代码
  end
end

命名规范

变量命名

变量名应该使用小写字母，多个单词之间用下划线（_）分隔，这被称为蛇形命名法（snake_case）。变量名应该具有描述性，清晰地表达变量所代表的含义。

user_name = "John Doe"
user_age = 30

避免使用单字母变量名，除非在非常简短的循环中：

(1..5).each do |i|
  puts i
end

对于布尔类型的变量，建议在变量名前加上“has_”、“is_”或“should_”等前缀，以清晰表明其代表的是一个布尔条件。

has_permission = true
is_admin = false
should_send_email = true

常量命名

常量使用大写字母，多个单词之间用下划线分隔。常量通常用于定义不会改变的值，如配置参数或数学常量。

MAX_USERS = 100
PI = 3.14159

方法命名

方法名同样使用蛇形命名法。方法名应该准确描述该方法的功能。对于布尔返回值的方法，建议使用“?”结尾，以表示其返回布尔值。

def user_exists?
  # 检查用户是否存在的逻辑
  true
end

def calculate_total
  # 计算总和的逻辑
  100
end

如果方法会修改调用它的对象的状态，通常在方法名后加上“!”，这被称为“bang方法”。

class String
  def reverse!
    self.replace(self.reverse)
  end
end

str = "hello"
str.reverse!
puts str # 输出 "olleh"

类命名

类名使用驼峰命名法（CamelCase），首字母大写。类名应该是名词，描述该类所代表的事物或概念。

class User
  # 类的定义
end

class OrderProcessor
  # 类的定义
end

注释

单行注释

单行注释使用“#”符号，用于对某一行代码或一小段代码进行解释。注释应该简洁明了，重点解释代码做了什么以及为什么这样做。

# 计算用户的平均分数
average_score = total_score / user_count

多行注释

对于较长的注释，可以使用多行注释。虽然Ruby没有像Java那样专门的多行注释符号（/*... */），但可以通过连续使用多个单行注释来实现类似效果。

# 这个方法用于处理用户登录逻辑。
# 它首先验证用户名和密码，
# 然后检查用户是否被锁定，
# 最后返回登录结果。
def user_login(username, password)
  # 方法代码
end

也可以使用文档注释（YARD风格），以“=begin”和“=end”包裹，这种注释常用于为类、方法等添加详细的文档说明，便于生成文档。

=begin
这个类代表一个用户对象。
它包含用户的基本信息和相关操作方法。
=end
class User
  # 类代码
end

代码结构

类的结构

一个类应该具有清晰的结构，通常先定义类的属性（使用attr_accessor等方法），然后是初始化方法（initialize），接着是其他实例方法。

class Product
  attr_accessor :name, :price

  def initialize(name, price)
    @name = name
    @price = price
  end

  def display_info
    puts "Name: #{@name}, Price: #{@price}"
  end
end

模块的使用

模块用于将相关的代码组织在一起，提供了一种避免命名冲突和代码复用的方式。模块中的方法可以是类方法或实例方法，具体取决于模块的使用场景。

module MathUtils
  def self.add(a, b)
    a + b
  end

  def multiply(a, b)
    a * b
  end
end

# 使用模块中的类方法
result = MathUtils.add(2, 3)
puts result # 输出 5

# 包含模块以使用实例方法
class Calculator
  include MathUtils
end

calc = Calculator.new
product = calc.multiply(4, 5)
puts product # 输出 20

控制流

if - else语句

if - else语句的使用应该保持清晰和简洁。如果条件语句较短，可以将其写在同一行，但要注意可读性。

if age >= 18
  puts "You are an adult."
else
  puts "You are a minor."
end

# 同一行写法
puts "You are an adult." if age >= 18

避免过度嵌套if - else语句，这会使代码难以阅读和维护。如果需要处理多个条件，可以考虑使用case - when语句。

case - when语句

case - when语句用于根据不同的条件执行不同的代码块，比多层嵌套的if - else更易读。

day = "Monday"
case day
when "Monday"
  puts "It's the start of the week."
when "Friday"
  puts "Weekend is coming!"
else
  puts "Just another day."
end

循环

在使用while和until循环时，确保循环条件清晰，并且有适当的终止条件，以避免无限循环。

count = 0
while count < 5
  puts count
  count += 1
end

count = 0
until count == 5
  puts count
  count += 1
end

each、map、select等迭代器方法在Ruby中非常常用，它们提供了更简洁和功能性的方式来处理集合。

numbers = [1, 2, 3, 4, 5]
numbers.each do |num|
  puts num
end

squared_numbers = numbers.map { |num| num * num }
puts squared_numbers # 输出 [1, 4, 9, 16, 25]

even_numbers = numbers.select { |num| num.even? }
puts even_numbers # 输出 [2, 4]

错误处理

异常捕获

使用begin - rescue - end块来捕获异常，确保代码在遇到错误时能够优雅地处理，而不是崩溃。

begin
  result = 10 / 0
rescue ZeroDivisionError => e
  puts "Error: #{e.message}"
end

在捕获异常时，尽量捕获具体的异常类型，而不是通用的Exception，这样可以更精确地处理不同类型的错误。

begin
  file = File.open('nonexistent_file.txt', 'r')
rescue Errno::ENOENT => e
  puts "File not found: #{e.message}"
end

异常抛出

如果方法遇到无法处理的情况，可以抛出异常。自定义异常可以通过继承StandardError类来实现。

class MyCustomError < StandardError; end

def some_method
  raise MyCustomError, "Something went wrong in the method."
end

begin
  some_method
rescue MyCustomError => e
  puts "Caught custom error: #{e.message}"
end

代码复用

继承

继承是实现代码复用的重要方式之一。子类可以继承父类的属性和方法，并根据需要进行扩展或重写。

class Animal
  def speak
    puts "I'm an animal."
  end
end

class Dog < Animal
  def speak
    puts "Woof!"
  end
end

dog = Dog.new
dog.speak # 输出 "Woof!"

模块混入

模块混入（include）允许一个类使用模块中定义的方法，实现了代码在不同类之间的复用，而无需通过继承。

module Flyable
  def fly
    puts "I can fly!"
  end
end

class Bird
  include Flyable
end

bird = Bird.new
bird.fly # 输出 "I can fly!"

最佳实践

使用块和迭代器

Ruby的块和迭代器提供了强大而简洁的方式来处理集合和控制流。尽可能使用它们，而不是编写显式的循环。

# 传统循环
numbers = [1, 2, 3, 4, 5]
sum = 0
for num in numbers
  sum += num
end
puts sum # 输出 15

# 使用迭代器
sum = numbers.inject(0) { |acc, num| acc + num }
puts sum # 输出 15

避免全局变量

全局变量（以$开头）在Ruby中应该尽量避免使用，因为它们会导致代码的可维护性和可测试性降低。全局变量的值在程序的任何地方都可以被修改，难以追踪其变化。

# 不推荐
$global_variable = "This is a global variable"

# 推荐使用实例变量或局部变量
class MyClass
  def initialize
    @instance_variable = "This is an instance variable"
  end

  def some_method
    local_variable = "This is a local variable"
    # 方法代码
  end
end

代码简洁性

保持代码简洁，避免编写冗余或复杂的代码。例如，使用Ruby的内置方法和语法糖来简化代码。

# 复杂写法
array = [1, 2, 3]
new_array = []
array.each do |num|
  new_array << num * 2
end
puts new_array # 输出 [2, 4, 6]

# 简洁写法
array = [1, 2, 3]
new_array = array.map { |num| num * 2 }
puts new_array # 输出 [2, 4, 6]

测试驱动开发（TDD）

在编写代码之前先编写测试用例，这有助于确保代码的正确性和可维护性。Ruby有许多测试框架，如Test::Unit和RSpec。

使用RSpec的示例：

# 假设我们有一个Calculator类
class Calculator
  def add(a, b)
    a + b
  end
end

# RSpec测试用例
require 'rspec'

describe Calculator do
  let(:calculator) { Calculator.new }

  describe '#add' do
    it 'adds two numbers correctly' do
      result = calculator.add(2, 3)
      expect(result).to eq(5)
    end
  end
end

通过遵循这些代码规范与风格指南，可以使Ruby代码更加清晰、易读、易维护，提高团队协作开发的效率，减少错误的发生，同时也能更好地与Ruby社区的最佳实践保持一致。在实际项目中，还可以根据项目的具体需求和团队的约定对这些规范进行适当的调整和补充。