Ruby Coding Style Guides

The Ruby Style Guide

风格可以用来区分从好到卓越。
-- Bozhidar Batsov

 

榜样很重要。
-- Officer Alex J. Murphy / RoboCop

有一件事情总是困扰着，作为Ruby程序员的我 - python 开发者都有一个很棒的编程风格参考
(PEP-8)，然而我们从没有一个官方的（公认）的 guide，文档化 Ruby 代码风格和最佳实践。而且我信赖这些风格（的作用）。我也相信很棒的 hacker 社区，比如 Ruby 社区，也应该有能力写出这梦寐以求的文档。

这份指南诞生于我们公司内部的 Ruby 编程准则(由值得你信赖的同志们编写)，我做正在做的工作基于这样的出发点： Ruby 社区的大多数成员会对我正在做的有兴趣这样的发点，并且这个世界上不需要一个公司内部的（编程）准则。一个面向 Ruby 编程的由社区驱动和社区认可一系列的实践，原则和风格形式是有益于大家的。

自从这个 guide（发表）以来，我收到了很多来自世界范围内 Ruby 社区的优秀的成员的回馈。感谢所有的建议和支持！集众家之力，我们可以创作出对每一个 Ruby 开发人员有益的资源。

补充，如果你正在使用 rails 你可能会希望查阅 Ruby on Rails 3 Style Guide。

Ruby 风格指南

这个 Ruby 风格指南推荐（一些）最佳实践使得现实世界中的 Ruby 程序员可以写出能够被其他现实世界的 Ruby 程序员维护的代码。一个风格指南反映了真实世界的使用习惯，同时一个风格指南伴随着一个观点那就是它被一些人们抵制因为它可能会导致风险的产生甚至毫无用处 —— 无论它有多好。

这个指南被分为几个相关联的 rules 的几节。我会尝试给 rules 添加合理的解释（如果它被省略那么我假设它相当的明显了）。

我并没有列举所有的 rules - 它们大多数基于我作为一个专业的软件工程师的广泛生涯、回馈和来自Ruby社区成员的建议以及各种备受推崇的 Ruby 编程资源，例如 "Programming Ruby 1.9"
和 "The Ruby Programming Language"。

很多地方的实践风格在 Ruby 社区没有一个明确的共识（sring 的字面引用，hash 里面的空格，点号在多行方法链的位置，等等 ）。在这样的场景中所有流行的风格都是被承认的并且它取决于你的选择和考虑。

这个指南仍然在工作进程中 - 一些 rules 缺乏例子，一些 rules 没有合适的例子来使得它们足够明了。在这期间一些问题将会提出 - just keep them in mind for now (以后将得到解决).

你可以使用 Transmuter. 来生成指南的 PDF 或者 HTML 副本。

RuboCop 是一个代码分析器, 它基于这个指南。

本指南的有下列语言的译文：

• Chinese Simplified
• Chinese Traditional
• French
• Japanese
• Spanish
• Vietnamese

目录表单

• 源代码布局
• 语法
• 命名
• 注释
  • 注解
• 类与模块
• 异常
• 集合
• 字符串
• 正则表达式
• 百分号和字面值
• 元编程
• 杂项
• 工具

源代码布局

所有风格都又丑又难读，自己的除外。几乎人人都这样想。
把 “自己的除外”拿掉，他们或许是对的...
-- Jerry Coffin (on indentation缩进)

• 使用 UTF-8 作为源文件编码。

• 每个缩进级别使用两个 spaces （又名软 tabs）. 不要硬 tabs

  # bad - four spacesdef some_method    do_somethingend# gooddef some_method  do_somethingend

• 使用 Unix-风格 换行符。(*BSD/Solaris/Linux/OSX 用户被为默认涵盖，Windows 用户必须特别小心.)

  \n是换行，英文是LineFeed，ASCII码是0xA。
  \r是回车，英文是Carriage Return ,ASCII码是0xD。
  windows下enter是 \n\r,unix下是\n,mac下是\r

  • 如果你正在使用 Git 你可能会想要添加下面的配置设置来保护你的项目（避免）Windows 蔓延过来的换行符:

  $ git config --global core.autocrlf true

• 不用使用 ; 来分割语句和表达式。以此推论 - 一行使用一个表达式

  # badputs 'foobar'; # superfluous semicolonputs 'foo'; puts 'bar' # two expression on the same line# goodputs 'foobar'puts 'foo'puts 'bar'puts 'foo', 'bar' # this applies to puts in particular

• 对于没有内容的类定义，尽可能使用单行类定义形式.

  # badclass FooError < StandardErrorend# okishclass FooError < StandardError; end# goodFooError = Class.new(StandardError)

• 避免单行方法。即便还是会受到一些人的欢迎，这里还是会有一些古怪的语法用起来很容易犯错.
  无论如何 - 应该一行不超过一个单行方法.

  # baddef too_much; something; something_else; end# okish - notice that the first ; is requireddef no_braces_method; body end# okish - notice that the second ; is optionaldef no_braces_method; body; end# okish - valid syntax, but no ; make it kind of hard to readdef some_method() body end# gooddef some_method  bodyend

  空方法是这个规则的例外。

  # gooddef no_op; end

• 操作符旁的空格，在逗号，冒号和分号后；在 { 旁和在 } 之前，大多数空格可能对 Ruby 解释（代码）无关，但是它的恰当使用是让代码变得易读的关键。

  sum = 1 + 2a, b = 1, 21 > 2 ? true : false; puts 'Hi'[1, 2, 3].each { |e| puts e }

  唯一的例外是当使用指数操作时：

  # bade = M * c ** 2# goode = M * c**2

  { 和 } 值得额外的澄清，自从它们被用于 块 和 hash 字面量，以及以表达式的形式嵌入字符串。
  对于 hash 字面量两种风格是可以接受的。

  # good - space after { and before }{ one: 1, two: 2 }# good - no space after { and before }{one: 1, two: 2}

  第一种稍微更具可读性（并且争议的是一般在 Ruby 社区里面更受欢迎）。
  第二种可以增加了 块 和 hash 可视化的差异。
  无论你选哪一种都行 - 但是最好保持一致。

  目前对于嵌入表达式，也有两个选择：

  # good - no spaces"string#{expr}"# ok - arguably more readable"string#{ expr }"

  第一种风格极为流行并且通常建议你与之靠拢。第二种，在另一方面，（有争议）更具可读性。
  如同 hash - 选取一个风格并且保持一致。

• 没有空格 (, [之后或者 ], )之前。

  some(arg).other[1, 2, 3].length

• ! 之后没有空格 .

  # bad! something# good!something

• when和case 缩进深度一致。我知道很多人会不同意这点，但是它是"The Ruby Programming Language" 和 "Programming Ruby"中公认的风格。

  # badcase  when song.name == 'Misty'    puts 'Not again!'  when song.duration > 120    puts 'Too long!'  when Time.now.hour > 21    puts "It's too late"  else    song.playend# goodcasewhen song.name == 'Misty'  puts 'Not again!'when song.duration > 120  puts 'Too long!'when Time.now.hour > 21  puts "It's too late"else  song.playend

  casewhen song.name == 'Misty'  puts 'Not again!'when song.duraton > 120  puts 'Too long!'when Time.now > 21  puts "It's too late"else  song.playend

• 当赋值一个条件表达式的结果给一个变量时，保持分支的缩排在同一层。

  # bad - pretty convolutedkind = case yearwhen 1850..1889 then 'Blues'when 1890..1909 then 'Ragtime'when 1910..1929 then 'New Orleans Jazz'when 1930..1939 then 'Swing'when 1940..1950 then 'Bebop'else 'Jazz'endresult = if some_cond  calc_somethingelse  calc_something_elseend# good - it's apparent what's going onkind = case year       when 1850..1889 then 'Blues'       when 1890..1909 then 'Ragtime'       when 1910..1929 then 'New Orleans Jazz'       when 1930..1939 then 'Swing'       when 1940..1950 then 'Bebop'       else 'Jazz'       endresult = if some_cond           calc_something         else           calc_something_else         end# good (and a bit more width efficient)kind =  case year  when 1850..1889 then 'Blues'  when 1890..1909 then 'Ragtime'  when 1910..1929 then 'New Orleans Jazz'  when 1930..1939 then 'Swing'  when 1940..1950 then 'Bebop'  else 'Jazz'  endresult =  if some_cond    calc_something  else    calc_something_else  end

• 在方法定义之间使用空行并且一个方法根据逻辑段来隔开。

  def some_method  data = initialize(options)  data.manipulate!  data.resultenddef some_methods  resultend

• 避免在一个方法调用的最后一个参数有逗号，特别是当参数不在另外一行。

  # bad - easier to move/add/remove parameters, but still not preferredsome_method(             size,             count,             color,           )# badsome_method(size, count, color, )# goodsome_method(size, count, color)

• 当给方法的参数赋默认值时，在 = 两边使用空格：

  # baddef some_method(arg1=:default, arg2=nil, arg3=[])  # do something...end# gooddef some_method(arg1 = :default, arg2 = nil, arg3 = [])  # do something...end

  虽然几本 Ruby 书建议用第一个风格，不过第二个风格在实践中更为常见（并可争议地可读性更高一点）。

• 避免在不需要的时候使用行继续符 \ 。实践中，
  除非用于连接字符串, 否则避免在任何情况下使用行继续符。

  # badresult = 1 - \         2# good (but still ugly as hell)result = 1 \         - 2long_string = 'First part of the long string' \              ' and second part of the long string'

• 采用连贯的多行方法链式风格。在 Ruby 社区有两种受欢迎的风格，它们都被认为很好
  - . 开头(选项 A) 和 尾随 . (选项 B) 。

  • (选项 A) 当一个链式方法调用需要在另一行继续时，将 . 放在第二行。

    # bad - need to consult first line to understand second lineone.two.three.  four# good - it's immediately clear what's going on the second lineone.two.three  .four

  • (选项 B) 当在另一行继续一个链式方法调用，将 . 放在第一行来识别要继续的表达式。

    # bad - need to read ahead to the second line to know that the chain continuesone.two.three  .four# good - it's immediately clear that the expression continues beyond the first lineone.two.three.  four

    在这里可以发现有关这两个另类风格的优点的讨论。

• 如果一个方法调用的跨度超过了一行，对齐它们的参数。当参数对齐因为行宽限制而不合适，
  在第一行之后单缩进也是可以接受的。

  # starting point (line is too long)def send_mail(source)  Mailer.deliver(to: '[e-mail]', from: '[e-mail]', subject: 'Important message', body: source.text)end# bad (double indent)def send_mail(source)  Mailer.deliver(      to: '[e-mail]',      from: '[e-mail]',      subject: 'Important message',      body: source.text)end# gooddef send_mail(source)  Mailer.deliver(to: '[e-mail]',                 from: '[e-mail]',                 subject: 'Important message',                 body: source.text)end# good (normal indent)def send_mail(source)  Mailer.deliver(    to: '[e-mail]',    from: '[e-mail]',    subject: 'Important message',    body: source.text  )end

• 对齐多行跨度的 array literals 的元素。

  # bad - single indentmenu_item = ['Spam', 'Spam', 'Spam', 'Spam', 'Spam', 'Spam', 'Spam', 'Spam',  'Baked beans', 'Spam', 'Spam', 'Spam', 'Spam', 'Spam']# goodmenu_item = [  'Spam', 'Spam', 'Spam', 'Spam', 'Spam', 'Spam', 'Spam', 'Spam',  'Baked beans', 'Spam', 'Spam', 'Spam', 'Spam', 'Spam']# goodmenu_item =  ['Spam', 'Spam', 'Spam', 'Spam', 'Spam', 'Spam', 'Spam', 'Spam',   'Baked beans', 'Spam', 'Spam', 'Spam', 'Spam', 'Spam']

• 大数值添加下划线来提高它们的可读性。

  # bad - how many 0s are there?num = 1000000# good - much easier to parse for the human brainnum = 1_000_000

• 使用 RDoc 以及它的惯例来撰写 API 文档。注解区块及 def 不要用空行隔开。

• 每一行限制在 80 个字符内。

• 避免行尾空格。

• 不要使用区块注释。它们不能由空白引导（=begin 必须顶头开始），并且不如普通注释容易辨认。

  # bad== begincomment lineanother comment line== end# good# comment line# another comment line

• 在 API 文档中使用 RDoc和它的公约。不要在注释代码块和def之间加入空行。

• 保持每一行少于80字符。

• 避免尾随空格。

语法

• 使用 :: 引用常量（包括类和模块）和构造器 (比如 Array() 或者 Nokogiri::HTML())。
  永远不要使用 :: 来调用方法。

  # badSomeClass::some_methodsome_object::some_method# goodSomeClass.some_methodsome_object.some_methodSomeModule::SomeClass::SOME_CONSTSomeModule::SomeClass()

• 使用括号将def的参数括起来。当方法不接收任何参数的时候忽略括号。

   # bad def some_method()   # body omitted end # good def some_method   # body omitted end # bad def some_method_with_arguments arg1, arg2   # body omitted end # good def some_method_with_arguments(arg1, arg2)   # body omitted end

• 从来不要使用 for， 除非你知道使用它的准确原因。大多数时候迭代器都可以用来替for。for 是由一组 each 实现的 (因此你正间接添加了一级)，但是有一个小道道 - for并不包含一个新的 scope (不像 each)并且在它的块中定义的变量在外面也是可以访问的。

  arr = [1, 2, 3]# badfor elem in arr do  puts elemend# note that elem is accessible outside of the for loopelem #=> 3# goodarr.each { |elem| puts elem }# elem is not accessible outside each's blockelem #=> NameError: undefined local variable or method `elem'

• 在多行的 if/unless 中坚决不要使用 then。

  # badif some_condition then  # body omittedend# goodif some_condition  # body omittedend

• 在多行的 if/unless 总是把条件放在与 if/unless 的同一行。

  # badif  some_condition  do_something  do_something_elseend# goodif some_condition  do_something  do_something_elseend

• 喜欢三元操作运算（?:）超过if/then/else/end结构。
  它更加普遍而且明显的更加简洁。

  # badresult = if some_condition then something else something_else end# goodresult = some_condition ? something : something_else

• 使用一个表达式在三元操作运算的每一个分支下面只使用一个表达式。也就是说三元操作符不要被嵌套。在这样的情形中宁可使用 if/else。

  # badsome_condition ? (nested_condition ? nested_something : nested_something_else) : something_else# goodif some_condition  nested_condition ? nested_something : nested_something_elseelse  something_elseend

• 不要使用 if x: ... - 它在Ruby 1.9中已经移除。使用三元操作运算代替。

  # badresult = if some_condition then something else something_else end# goodresult = some_condition ? something : something_else

• 利用 if and case 是表达式这样的事实它们返回一个结果。

  # badif condition  result = xelse  result = yend# goodresult =  if condition    x  else    y  end

• 在 one-line cases 的时候使用 when x then ...。替代的语法when x: xxx已经在Ruby 1.9中移除。

• 不要使用when x; ...。查看上面的规则。

• 使用 ! 替代 not.

  # 差 - 因为操作符有优先级，需要用括号。x = (not something)# goodx = !something

• 避免使用 !!.

  # badx = 'test'# obscure nil checkif !!x  # body omittedendx = false# double negation is useless on booleans!!x # => false# goodx = 'test'unless x.nil?  # body omittedend

• and 和 or 这两个关键字被禁止使用了。它名不符实。总是使用 && 和 || 来取代。

  # bad# boolean expressionif some_condition and some_other_condition  do_somethingend# control flowdocument.saved? or document.save!# good# boolean expressionif some_condition && some_other_condition  do_somethingend# control flowdocument.saved? || document.save!

• 避免多行的 ? :（三元操作符）；使用 if/unless 来取代。

• 单行主体喜欢使用 if/unless 修饰符。另一个好方法是使用 &&/|| 控制流程。

  # badif some_condition  do_somethingend# gooddo_something if some_condition# another good optionsome_condition && do_something

• 布尔表达式使用&&/||, and/or用于控制流程。（经验Rule:如果你必须使用额外的括号（表达逻辑），那么你正在使用错误的的操作符。）

  # boolean expressionif some_condition && some_other_condition  do_somethingend# control flowdocument.save? or document.save!

• 避免多行?:(三元操作运算)，使用 if/unless 替代。

• 在单行语句的时候喜爱使用 if/unless 修饰符。另一个好的选择就是使 and/or 来做流程控制。

  # badif some_condition  do_somethingend# gooddo_something if some_condition# another good optionsome_condition and do_something

• 永远不要使用 unless 和 else 组合。将它们改写成肯定条件。

  # badunless success?  puts 'failure'else  puts 'success'end# goodif success?  puts 'success'else  puts 'failure'end

• 不用使用括号包含 if/unless/while 的条件。

  # badif (x > 10)  # body omittedend# goodif x > 10  # body omittedend

• 在多行 while/until 中不要使用 while/until condition do 。

  # badwhile x > 5 do  # body omittedenduntil x > 5 do  # body omittedend# goodwhile x > 5  # body omittedenduntil x > 5  # body omittedend

• 当你有单行主体时，尽量使用 while/until 修饰符。

  # badwhile some_condition  do_somethingend# gooddo_something while some_condition

• 否定条件判断尽量使用 until 而不是 while 。

  # baddo_something while !some_condition# gooddo_something until some_condition

• 循环后条件判断使用 Kernel#loop 和 break，而不是 begin/end/until 或者 begin/end/while。

   # bad   begin     puts val     val += 1   end while val < 0   # good   loop do     puts val     val += 1     break unless val < 0   end

• 忽略围绕内部 DSL 方法参数的括号 (如：Rake, Rails, RSpec)，Ruby 中带有 "关键字" 状态的方法（如：attr_reader，puts）以及属性存取方法。所有其他的方法调用使用括号围绕参数。

  class Person  attr_reader :name, :age  # omittedendtemperance = Person.new('Temperance', 30)temperance.nameputs temperance.agex = Math.sin(y)array.delete(e)bowling.score.should == 0

• 忽略隐式选项 hash 外部的花括号。

  # baduser.set({ name: 'John', age: 45, permissions: { read: true } })# gooduser.set(name: 'John', age: 45, permissions: { read: true })

• 内部 DSL 方法的外部括号和大括号。

  class Person < ActiveRecord::Base  # bad  validates(:name, { presence: true, length: { within: 1..10 } })  # good  validates :name, presence: true, length: { within: 1..10 }end

• 方法调用不需要参数，那么忽略圆括号。

  # badKernel.exit!()2.even?()fork()'test'.upcase()# goodKernel.exit!2.even?fork'test'.upcase

• 在单行代码块的时候宁愿使用 {...} 而不是 do...end。避免在多行代码块使用 {...} (多行链式通常变得非常丑陋)。通常使用 do...end 来做 流程控制 和 方法定义 (例如 在 Rakefiles 和某些 DSLs 中)。避免在链式调用中使用 do...end。

  names = ['Bozhidar', 'Steve', 'Sarah']# badnames.each do |name|  puts nameend# goodnames.each { |name| puts name }# badnames.select do |name|  name.start_with?('S')end.map { |name| name.upcase }# goodnames.select { |name| name.start_with?('S') }.map { |name| name.upcase }

  有人会争论多行链式看起来和使用 {...} 一样工作，但是他们问问自己 - 这样的代码真的有可读性码并且为什么代码块中的内容不能被提取到美丽的方法中。

• 考虑使用明确的块参数来避免写入的块字面量仅仅传递参数的给另一个块。小心性能的影响，即使，
  块被转换成了 Proc。

  require 'tempfile'# baddef with_tmp_dir  Dir.mktmpdir do |tmp_dir|    Dir.chdir(tmp_dir) { |dir| yield dir }  # block just passes arguments  endend# gooddef with_tmp_dir(&block)  Dir.mktmpdir do |tmp_dir|    Dir.chdir(tmp_dir, &block)  endendwith_tmp_dir do |dir|  puts "dir is accessible as parameter and pwd is set: #{dir}"end

• 避免在不需要流的控制使用 return。

  # baddef some_method(some_arr)  return some_arr.sizeend# gooddef some_method(some_arr)  some_arr.sizeend

• 避免在不需要的地方使用 self(它仅仅在调用一些 self 做写访问的时候需要)(It is only required when calling a self write accessor.)

  # baddef ready?  if self.last_reviewed_at > self.last_updated_at    self.worker.update(self.content, self.options)    self.status = :in_progress  end  self.status == :verifiedend# gooddef ready?  if last_reviewed_at > last_updated_at    worker.update(content, options)    self.status = :in_progress  end  status == :verifiedend

• 作为一个必然的结果，避免将方法（参数）放于局部变量阴影之下除非它们是相等的。

  class Foo  attr_accessor :options  # ok  def initialize(options)    self.options = options    # both options and self.options are equivalent here  end  # bad  def do_something(options = {})    unless options[:when] == :later      output(self.options[:message])    end  end  # good  def do_something(params = {})    unless params[:when] == :later      output(options[:message])    end  endend

• 不要在条件表达式里使用 = （赋值）的返回值，除非条件表达式在圆括号内被赋值。
  这是一个相当流行的 ruby 方言，有时被称为 safe assignment in condition。

  # bad (+ a warning)if v = array.grep(/foo/)  do_something(v)  ...end# good (MRI would still complain, but RuboCop won't)if (v = array.grep(/foo/))  do_something(v)  ...end# goodv = array.grep(/foo/)if v  do_something(v)  ...end

• 在任何可以的地方使用快捷的 self assignment 操作符。

  # badx = x + yx = x * yx = x**yx = x / yx = x || yx = x && y# goodx += yx *= yx **= yx /= yx ||= yx &&= y

• 只有在变量没有被初始化的时候使用 ||= 来初始化变量。

  # set name to Vozhidar, only if it's nil or falsename ||= 'Bozhidar'

• 不要使用||=来初始化布尔变量。（想想如果当前值为false的时候会发生什么。）

  # bad - would set enabled to true even if it was falseenable ||= true# goodenabled = true if enabled.nil?

• 使用 &&= 来预处理变量不确定是否存在的变量。使用 &&= 仅仅在（变量）存在的时候
  才会改变值，除去了使用 if 来检查它的存在性。

  # badif something  something = something.downcaseend# badsomething = something ? nil : something.downcase# oksomething = something.downcase if something# goodsomething = something && something.downcase# bettersomething &&= something.downcase

• 避免全等（case equality）=== 操作符的使用。从名称可知，这是 case 表达式的隐式使用并且在 case 语句外的场合使用会产生难以理解的代码。

  # badArray === something(1..100) === 7/something/ === some_string# goodsomething.is_a?(Array)(1..100).include?(7)some_string =~ /something/

• 避免使用 Perl 的指定变量风格（比如，$:，$; 等等。）。它们相当神秘，不鼓励在单行代码之外使用它们。
  使用 English 库提供的友好别名。

  # bad$:.unshift File.dirname(__FILE__)# goodrequire 'English'$LOAD_PATH.unshift File.dirname(__FILE__)

• 从来不要在方法名和（参数）开括号之间使用空格。

  # badf (3+2) + 1# goodf(3 + 2) +1

• 如果方法的第一个参数以开括号开始，通常使用括号把它们全部括起来。例如f((3 + 2) + 1)。

• 通常使用 -w 选项运行 Ruby 解释器，在你忘记上面所诉规则，ruby 将会提示你。

• 定义单行块使用新的 lambda 语法。定义多行块中使用 lambda 方法。

  # badl = lambda { |a, b| a + b }l.call(1, 2)# correct, but looks extremely awkwardl = ->(a, b) do  tmp = a * 7  tmp * b / 50end# goodl = ->(a, b) { a + b }l.call(1, 2)l = lambda do |a, b|  tmp = a * 7  tmp * b / 50end

• 用 proc 而不是 Proc.new。

  # badp = Proc.new { |n| puts n }# goodp = proc { |n| puts n }

• 匿名方法 和 块 用 proc.call() 而不是 proc[] 或 proc.()。

  # bad - looks similar to Enumeration accessl = ->(v) { puts v }l[1]# also bad - uncommon syntaxl = ->(v) { puts v }l.(1)# goodl = ->(v) { puts v }l.call(1)

• 未使用的块参数和局部变量使用 _。它也可以接受通过 _ 来使用（即使它有少了些描述性）。
  这个惯例由 Ruby 解释器以及 RuboCop 这样的工具组织其将会抑制它们的未使用参数警告。

  # badresult = hash.map { |k, v| v + 1 }def something(x)  unused_var, used_var = something_else(x)  # ...end# goodresult = hash.map { |_k, v| v + 1 }def something(x)  _unused_var, used_var = something_else(x)  # ...end# goodresult = hash.map { |_, v| v + 1 }def something(x)  _, used_var = something_else(x)  # ...end

• 使用 $stdout/$stderr/$stdin 而不是 STDOUT/STDERR/STDIN。STDOUT/STDERR/STDIN 是常量，虽然在 Ruby 中是可以给常量重新赋值的（可能是重定向到某个流），但解释器会警告如果你执意这样。

• 使用 warn 而不是 $stderr.puts。除了更加清晰简洁，如果你需要的话，
  warn 还允许你抑制（suppress）警告（通过 -W0 将警告级别设为 0）。

• 倾向使用 sprintf 和它的别名 format 而不是相当隐晦的 String#% 方法.

  # bad'%d %d' % [20, 10]# => '20 10'# goodsprintf('%d %d', 20, 10)# => '20 10'# goodsprintf('%{first} %{second}', first: 20, second: 10)# => '20 10'format('%d %d', 20, 10)# => '20 10'# goodformat('%{first} %{second}', first: 20, second: 10)# => '20 10'

• 倾向使用 Array#join 而不是相当隐晦的使用字符串作参数的 Array#*。

  # bad%w(one two three) * ', '# => 'one, two, three'# good%w(one two three).join(', ')# => 'one, two, three'

• 当处理你希望像 Array 那样对待的变量，但是你不确定它是一个数组时，
  使用 [*var] or Array() 而不是显式的 Array 检查。

  # badpaths = [paths] unless paths.is_a? Arraypaths.each { |path| do_something(path) }# good[*paths].each { |path| do_something(path) }# good (and a bit more readable)Array(paths).each { |path| do_something(path) }

• 尽量使用范围或 Comparable#between? 来替换复杂的逻辑比较。

  # baddo_something if x >= 1000 && x <= 2000# gooddo_something if (1000..2000).include?(x)# gooddo_something if x.between?(1000, 2000)

• 尽量用谓词方法而不是使用 ==。比较数字除外。

  # badif x % 2 == 0endif x % 2 == 1endif x == nilend# goodif x.even?endif x.odd?endif x.nil?endif x.zero?endif x == 0end

• 避免使用 BEGIN 区块。

• 使用 Kernel#at_exit 。永远不要用 END 区块。

  # badEND { puts 'Goodbye!' }# goodat_exit { puts 'Goodbye!' }

• 避免使用 flip-flops 。

• 避免使用嵌套的条件来控制流程。
  当你可能断言不合法的数据，使用一个防御语句。一个防御语句是一个在函数顶部的条件声明，这样如果数据不合法就能尽快的跳出函数。

  # bad  def compute_thing(thing)    if thing[:foo]      update_with_bar(thing)      if thing[:foo][:bar]        partial_compute(thing)      else        re_compute(thing)      end    end  end# good  def compute_thing(thing)    return unless thing[:foo]    update_with_bar(thing[:foo])    return re_compute(thing) unless thing[:foo][:bar]    partial_compute(thing)  end

  命名

The only real difficulties in programming are cache invalidation and
naming things. <br/>
-- Phil Karlton
程式设计的真正难题是替事物命名及使缓存失效。<br/>
-- Phil Karlton

• 用英语命名标识符。

  # bad - identifier using non-ascii charactersзаплата = 1_000# bad - identifier is a Bulgarian word, written with Latin letters (instead of Cyrillic)zaplata = 1_000# goodsalary = 1_000

• 使用snake_case的形式给变量和方法命名。

  # bad:'some symbol':SomeSymbol:someSymbolsomeVar = 5def someMethod  ...enddef SomeMethod ...end# good:some_symboldef some_method  ...end

• Snake case: punctuation is removed and spaces are replaced by single underscores. Normally the letters share the same case (either UPPER_CASE_EMBEDDED_UNDERSCORE or lower_case_embedded_underscore) but the case can be mixed

• 使用CamelCase(駝峰式大小寫)的形式给类和模块命名。(保持使用缩略首字母大写的方式如HTTP,
  RFC, XML)

  # badclass Someclass  ...endclass Some_Class  ...endclass SomeXml  ...end# goodclass SomeClass  ...endclass SomeXML  ...end

• 使用 snake_case 来命名文件, 例如 hello_world.rb。

• 以每个源文件中仅仅有单个 class/module 为目的。按照 class/module 来命名文件名，但是替换 CamelCase 为 snake_case。

• 使用SCREAMING_SNAKE_CASE给常量命名。

  # badSomeConst = 5# goodSOME_CONST = 5

• 在表示判断的方法名（方法返回真或者假）的末尾添加一个问号（如Array#empty?）。
  方法不返回一个布尔值，不应该以问号结尾。

• 可能会造成潜在“危险”的方法名（如修改 self或者 参数的方法，exit! (不是像 exit 执行完成项)等）应该在末尾添加一个感叹号如果这里存在一个该 危险 方法的安全版本。

  # bad - there is not matching 'safe' methodclass Person  def update!  endend# goodclass Person  def update  endend# goodclass Person  def update!  end  def update  endend

• 如果可能的话，根据危险方法（bang）来定义对应的安全方法（non-bang）。

  class Array  def flatten_once!    res = []    each do |e|      [*e].each { |f| res << f }    end    replace(res)  end  def flatten_once    dup.flatten_once!  endend

• 当在短的块中使用 reduce 时，命名参数 |a, e| (accumulator, element)。

  #Combines all elements of enum枚举 by applying a binary operation, specified by a block or a symbol that names a method or operator.# Sum some numbers(5..10).reduce(:+)                            #=> 45#reduce# Same using a block and inject(5..10).inject {|sum, n| sum + n }            #=> 45 #inject注入# Multiply some numbers(5..10).reduce(1, :*)                         #=> 151200# Same using a block(5..10).inject(1) {|product, n| product * n } #=> 151200

• 在定义二元操作符时，把参数命名为 other （<< 与 [] 是这条规则的例外，因为它们的语义不同）。

  def +(other)  # body omittedend

• map 优先于 collect，find 优先于 detect，select 优先于 find_all，reduce 优先于inject，size 优先于 length。以上的规则并不绝定，如果使用后者能提高代码的可读性，那么尽管使用它们。有押韵的方法名（如 collect，detect，inject）继承于 SmallTalk 语言，它们在其它语言中并不是很通用。鼓励使用 select 而不是 find_all 是因为 select与 reject 一同使用时很不错，并且它的名字具有很好的自解释性。

• 不要使用 count 作为 size 的替代。对于 Enumerable 的 Array 以外的对象将会迭代整个集合来
  决定它的尺寸。

  # badsome_hash.count# goodsome_hash.size

• 倾向使用 flat_map 而不是 map + flatten 的组合。
  这并不适用于深度大于 2 的数组，举个例子，如果 users.first.songs == ['a', ['b', 'c']] ，则使用 map + flatten 的组合，而不是使用 flat_map 。
  flat_map 将数组变平坦一个层级，而 flatten 会将整个数组变平坦。

  # badall_songs = users.map(&:songs).flatten.uniq# goodall_songs = users.flat_map(&:songs).uniq

• 使用 reverse_each 代替 reverse.each。reverse_each 不会分配一个新数组并且这是好事。

  # badarray.reverse.each { ... }# goodarray.reverse_each { ... }

注释

Good code is its own best documentation. As you're about to add a
comment, ask yourself, "How can I improve the code so that this
comment isn't needed?" Improve the code and then document it to make
it even clearer. <br/>
-- Steve McConnell
好的代码在于它有好的文档。当你打算添加一个注释，问问自己，“我该做的是怎样提高代码质量，那么这个注释是不是不需要了？”提高代码并且给他们添加文档使得它更加简洁。<br/>
-- Steve McConnell

• 写出自解释文档代码，然后让这部分歇息吧。这不是说着玩。
• 使用英文编写注释。
• 使用一个空格将注释与符号隔开。
• 注释超过一个单词了，应句首大写并使用标点符号。句号后使用 一个空格

• 避免多余的注释。

  # badcounter += 1 # increments counter by one

• 随时更新注释，没有注释比过期的注释更好。

Good code is like a good joke - it needs no explanation. <br/>
-- Russ Olsen

• Avoid writing comments to explain bad code. Refactor the code to
  make it self-explanatory. (Do or do not - there is no try. --Yoda)

• 不要为糟糕的代码写注释。重构它们，使它们能够“自解释”。(Do or do not - there is no try.)

注解

• 注解应该写在紧接相关代码的上方。
• 注解关键字后跟一个冒号和空格，然后是描述问题的记录。

• 如果需要多行来描述问题，随后的行需要在 # 后面缩进两个空格。

  def bar  # FIXME: This has crashed occasionally since v3.2.1. It may  #  be related to the BarBazUtil upgrade.  baz(:quux)end

• 如果问题相当明显，那么任何文档就多余了，注解也可以（违规的）在行尾而没有任何备注。这种用法不应当在一般情况下使用，也不应该是一个 rule。

  def bar  sleep 100 # OPTIMIZEend

• 使用 TODO 来备注缺失的特性或者在以后添加的功能。

• 使用 FIXME 来备注有问题需要修复的代码。

• 使用 OPTIMIZE 来备注慢的或者低效的可能引起性能问题的代码。

• 使用 HACK 来备注那些使用问题代码的地方可能需要重构。

• 使用 REVIEW 来备注那些需要反复查看确认工作正常的代码。例如： REVIEW: 你确定客户端是怎样正确的完成 X 的吗？

• 使用其他自定义的关键字如果认为它是合适的，但是确保在你的项目的 README 或者类似的地方注明。

类与模块

• 在 class 定义里使用一致的结构。

  class Person  # extend and include go first  extend SomeModule  include AnotherModule  # constants are next  SOME_CONSTANT = 20  # afterwards we have attribute macros  attr_reader :name  # followed by other macros (if any)  validates :name  # public class methods are next in line  def self.some_method  end  # followed by public instance methods  def some_method  end  # protected and private methods are grouped near the end  protected  def some_protected_method  end  private  def some_private_method  endend

• 倾向使用 module，而不是只有类方法的 class。类别应该只在创建实例是合理的时候使用。

  # badclass SomeClass  def self.some_method    # body omitted  end  def self.some_other_method  endend# goodmodule SomeClass  module_function  def some_method    # body omitted  end  def some_other_method  endend

• 当你希望将模块的实例方法变成 class 方法时，偏爱使用 module_function 胜过 extend self。

  # badmodule Utilities  extend self  def parse_something(string)    # do stuff here  end  def other_utility_method(number, string)    # do some more stuff  endend# goodmodule Utilities  module_function  def parse_something(string)    # do stuff here  end  def other_utility_method(number, string)    # do some more stuff  endend

• When designing class hierarchies make sure that they conform to the
  Liskov Substitution Principle.

• 在设计类层次的时候确保他们符合 Liskov Substitution Principle 原则。(译者注: LSP原则大概含义为: 如果一个函数中引用了父类的实例, 则一定可以使用其子类的实例替代, 并且函数的基本功能不变. (虽然功能允许被扩展))

  Liskov替换原则：子类型必须能够替换它们的基类型 <br/>
  1. 如果每一个类型为T1的对象o1，都有类型为T2的对象o2，使得以T1定义的所有程序P在所有的对象o1都代换为o2时,程序P的行为没有变化，那么类型T2是类型T1的子类型。 <br/>
  2. 换言之，一个软件实体如果使用的是一个基类的话，那么一定适用于其子类，而且它根本不能察觉出基类对象和子类对象的区别。只有衍生类替换基类的同时软件实体的功能没有发生变化，基类才能真正被复用。 <br/>
  3. 里氏代换原则由Barbar Liskov(芭芭拉.里氏)提出，是继承复用的基石。 <br/>
  4. 一个继承是否符合里氏代换原则，可以判断该继承是否合理（是否隐藏有缺陷）。

• 努力使你的类尽可能的健壮 [SOLID](http://en.wikipedia.org/wiki/SOLID_object-oriented_design\))。(

• 总是为你自己的类提供 to_s 方法, 用来表现这个类（实例）对象包含的对象.

  class Person  attr_reader :first_name, :last_name  def initialize(first_name, last_name)    @first_name = first_name    @last_name = last_name  end  def to_s    "#@first_name #@last_name"  endend

• 使用 attr 功能成员来定义各个实例变量的访问器或者修改器方法。

  # badclass Person  def initialize(first_name, last_name)    @first_name = first_name    @last_name = last_name  end  def first_name    @first_name  end  def last_name    @last_name  endend# goodclass Person  attr_reader :first_name, :last_name  def initialize(first_name, last_name)    @first_name = first_name    @last_name = last_name  endend

• 避免使用 attr。使用 attr_reader 和 attr_accessor 作为替代。

  # bad - creates a single attribute accessor (deprecated in 1.9)attr :something, trueattr :one, :two, :three # behaves as attr_reader# goodattr_accessor :somethingattr_reader :one, :two, :three

• 考虑使用 Struct.new, 它可以定义一些琐碎的 accessors,
  constructor（构造函数） 和 comparison（比较） 操作。

  # goodclass Person  attr_reader :first_name, :last_name  def initialize(first_name, last_name)    @first_name = first_name    @last_name = last_name  endend# betterclass Person < Struct.new(:first_name, :last_name)end

• 考虑使用 Struct.new，它替你定义了那些琐碎的存取器（accessors），构造器（constructor）以及比较操作符（comparison operators）。

  # goodclass Person  attr_accessor :first_name, :last_name  def initialize(first_name, last_name)    @first_name = first_name    @last_name = last_name  endend# betterPerson = Struct.new(:first_name, :last_name) doend

• 不要去 extend 一个 Struct.new - 它已经是一个新的 class。扩展它会产生一个多余的 class 层级
  并且可能会产生怪异的错误如果文件被加载多次。

• 考虑添加工厂方法来提供灵活的方法来创建特定类实例。

  class Person  def self.create(potions_hash)    # body omitted  endend

• 鸭子类型（duck-typing）优于继承。

  # badclass Animal  # abstract method  def speak  endend# extend superclassclass Duck < Animal  def speak    puts 'Quack! Quack'  endend# extend superclassclass Dog < Animal  def speak    puts 'Bau! Bau!'  endend# goodclass Duck  def speak    puts 'Quack! Quack'  endendclass Dog  def speak    puts 'Bau! Bau!'  endend

• Avoid the usage of class (@@) variables due to their "nasty" behavior
  in inheritance.

• 避免使用类变量（@@）因为他们讨厌的继承习惯（在子类中也可以修改父类的类变量）。

  class Parent  @@class_var = 'parent'  def self.print_class_var    puts @@class_var  endendclass Child < Parent  @@class_var = 'child'endParent.print_class_var # => will print "child"

  正如上例看到的, 所有的子类共享类变量, 并且可以直接修改类变量,此时使用类实例变量是更好的主意.

• 根据方法的用途为他们分配合适的可见度( private, protected )，不要让所有的方法都是 public (这是默认设定)。这是Ruby 不是 Python。

• public, protected, 和 private 等可见性关键字应该和其（指定）的方法具有相同的缩进。并且不同的可见性关键字之间留一个空格。

  class SomeClass  def public_method    # ...  end  private  def private_method    # ...  end  def another_private_method    # ...  endend

• 使用 def self.method 来定义单例方法. 当代码重构时, 这将使得代码更加容易因为类名是不重复的.

  class TestClass  # bad  def TestClass.some_method    # body omitted  end  # good  def self.some_other_method    # body omitted  end  # Also possible and convenient when you  # have to define many singleton methods.  class << self    def first_method      # body omitted    end    def second_method_etc      # body omitted    end  endend

  class SingletonTest  def size    25  endendtest1 = SingletonTest.newtest2 = SingletonTest.newdef test2.size  10endtest1.size # => 25test2.size # => 10

  本例中，test1 與 test2 屬於同一類別，但 test2 具有重新定義的 size 方法，因此兩者的行為會不一樣。只給予單一物件的方法稱為单例方法 (singleton method)。

异常

• 单个异常使用 fail 关键字仅仅当捕获一个异常并且反复抛出这个异常(因为这里你不是失败，而是准确的并且故意抛出一个异常)。

  begin  fail 'Oops'rescue => error  raise if error.message != 'Oops'end

• 不要为 fail/raise 指定准确的 RuntimeError。

  # badfail RuntimeError, 'message'# good - signals a RuntimeError by defaultfail 'message'

• 宁愿提供一个异常类和一条消息作为 fail/raise 的两个参数，而不是一个异常实例。

  # badfail SomeException.new('message')# Note that there is no way to do `fail SomeException.new('message'), backtrace`.# goodfail SomeException, 'message'# Consistent with `fail SomeException, 'message', backtrace`.

• 不要在 ensure 块中返回。如果你明确的从 ensure 块中的某个方法中返回，返回将会优于任何抛出的异常，并且尽管没有异常抛出也会返回。实际上异常将会静静的溜走。

  def foo  begin    fail  ensure    return 'very bad idea'  endend

• Use implicit begin blocks when possible.如果可能使用隐式 begin 代码块。

  # baddef foo  begin    # main logic goes here  rescue    # failure handling goes here  endend# gooddef foo  # main logic goes hererescue  # failure handling goes hereend

• 通过 contingency methods 偶然性方法。 (一个由 Avdi Grimm 创造的词) 来减少 begin 区块的使用。

  # badbegin  something_that_might_failrescue IOError  # handle IOErrorendbegin  something_else_that_might_failrescue IOError  # handle IOErrorend# gooddef with_io_error_handling   yieldrescue IOError  # handle IOErrorendwith_io_error_handling { something_that_might_fail }with_io_error_handling { something_else_that_might_fail }

• 不要抑制异常输出。

  # badbegin  # an exception occurs hererescue SomeError  # the rescue clause does absolutely nothingend# baddo_something rescue nil

• 避免使用 rescue 的修饰符形式。

  # bad - this catches exceptions of StandardError class and its descendant classesread_file rescue handle_error($!)# good - this catches only the exceptions of Errno::ENOENT class and its descendant classesdef foo  read_filerescue Errno::ENOENT => ex  handle_error(ex)end

• 不要用异常来控制流。

  # badbegin  n / drescue ZeroDivisionError  puts "Cannot divide by 0!"end# goodif d.zero?  puts "Cannot divide by 0!"else  n / dend

• 应该总是避免拦截(最顶级的) Exception 异常类。这里(ruby自身)将会捕获信号并且调用 exit，需要你使用 kill -9 杀掉进程。

  # badbegin  # calls to exit and kill signals will be caught (except kill -9)  exitrescue Exception  puts "you didn't really want to exit, right?"  # exception handlingend# goodbegin  # a blind rescue rescues from StandardError, not Exception as many  # programmers assume.rescue => e  # exception handlingend# also goodbegin  # an exception occurs hererescue StandardError => e  # exception handlingend

• 将更具体的异常放在救援（rescue）链的上方，否则他们将不会被救援。

  # badbegin  # some coderescue Exception => e  # some handlingrescue StandardError => e  # some handlingend# goodbegin  # some coderescue StandardError => e  # some handlingrescue Exception => e  # some handlingend

• 在 ensure 区块中释放你程式获得的外部资源。

  f = File.open('testfile')begin  # .. processrescue  # .. handle errorensure  f.close unless f.nil?end

• 除非必要, 尽可能使用 Ruby 标准库中异常类，而不是引入一个新的异常类。(而不是派生自己的异常类)

集合

• 倾向数组及哈希的字面表示法(除非你需要传递参数到它们的构造函数中)。

  # badarr = Array.newhash = Hash.new# goodarr = []hash = {}

• 当你需要元素为单词（没有空格和特殊符号）的数组的时候总是使用 %w 的方式来定义字符串数组。应用这条规则仅仅在两个或多个数组。

  # badSTATES = ['draft', 'open', 'closed']# goodSTATES = %w(draft open closed)

• 当你需要一个符号的数组（并且不需要保持 Ruby 1.9 兼容性）时，使用 %i。仅当数组只有两个及以上元素时才应用这个规则。

  # badSTATES = [:draft, :open, :closed]# goodSTATES = %i(draft open closed)

• 避免在 Array 或者 Hash 的最后一项后面出现逗号，特别是当这些条目不在一行。

  # bad - easier to move/add/remove items, but still not preferredVALUES = [           1001,           2020,           3333,         ]# badVALUES = [1001, 2020, 3333, ]# goodVALUES = [1001, 2020, 3333]

• 避免在数组中创造巨大的间隔。

  arr = []arr[100] = 1 # now you have an array with lots of nils

• 当访问一个数组的第一个或者最后一个元素，倾向使用 first 或 last 而不是 [0] 或 [-1]。

• 如果要确保元素唯一, 则使用 Set 代替 Array .Set 更适合于无顺序的, 并且元素唯一的集合, 集合具有类似于数组一致性操作以及哈希的快速查找.

• 尽可能使用符号代替字符串作为哈希键.

  # badhash = { 'one' => 1, 'two' => 2, 'three' => 3 }# goodhash = { one: 1, two: 2, three: 3 }

• 避免使用易变对象作为哈希键。

• 优先使用 1.9 的新哈希语法当你的哈希键是符号。

  # badhash = { :one => 1, :two => 2, :three => 3 }# goodhash = { one: 1, two: 2, three: 3 }

• 在相同的 hash 字面量中不要混合 Ruby 1.9 hash 语法和箭头形式的 hash。当你
  得到的 keys 不是符号的时候转换为箭头形式的语法。

  # bad{ a: 1, 'b' => 2 }# good{ :a => 1, 'b' => 2 }

• 用 Hash#key? 不用 Hash#has_key? 以及用 Hash#value?, 不用 Hash#has_value? Matz 提到过 长的形式在考虑被弃用。

  # badhash.has_key?(:test)hash.has_value?(value)# goodhash.key?(:test)hash.value?(value)

• 在处理应该存在的哈希键时，使用 fetch。

  heroes = { batman: 'Bruce Wayne', superman: 'Clark Kent' }# bad - if we make a mistake we might not spot it right awayheroes[:batman] # => "Bruce Wayne"heroes[:supermann] # => nil# good - fetch raises a KeyError making the problem obviousheroes.fetch(:supermann)

• 在使用 fetch 时，使用第二个参数设置默认值而不是使用自定义的逻辑。

   batman = { name: 'Bruce Wayne', is_evil: false }   # bad - if we just use || operator with falsy value we won't get the expected result   batman[:is_evil] || true # => true   # good - fetch work correctly with falsy values   batman.fetch(:is_evil, true) # => false

• 尽量用 fetch 加区块而不是直接设定默认值。

   batman = { name: 'Bruce Wayne' }   # bad - if we use the default value, we eager evaluate it   # so it can slow the program down if done multiple times   batman.fetch(:powers, get_batman_powers) # get_batman_powers is an expensive call   # good - blocks are lazy evaluated, so only triggered in case of KeyError exception   batman.fetch(:powers) { get_batman_powers }

• 当你需要从一个 hash 连续的取回一系列的值的时候使用 Hash#values_at。

  # bademail = data['email']nickname = data['nickname']# goodemail, username = data.values_at('email', 'nickname')

• 记住, 在 Ruby1.9 中, 哈希的表现不再是无序的. (译者注: Ruby1.9 将会记住元素插入的序列)

• 当遍历一个集合的同时, 不要修改这个集合。

字符串

• 优先使用 字符串插值 来代替 字符串串联。

  # bademail_with_name = user.name + ' <' + user.email + '>'# goodemail_with_name = "#{user.name} <#{user.email}>"# goodemail_with_name = format('%s <%s>', user.name, user.email)

• Consider padding string interpolation code with space. It more clearly sets the
  code apart from the string.考虑使用空格填充字符串插值。它更明确了除字符串的插值来源。

  "#{ user.last_name }, #{ user.first_name }"

• Consider padding string interpolation code with space. It more clearly sets the
  code apart from the string.
  考虑替字符串插值留白。這使插值在字符串里看起來更清楚。

  "#{ user.last_name }, #{ user.first_name }"

• 采用一致的字符串字面量引用风格。这里有在社区里面受欢迎的两种风格，它们都被认为非常好 -
  默认使用单引号（选项 A）以及双引号风格（选项 B）。

  • (Option A) 当你不需要字符串插值或者例如 \t， \n， ' 这样的特殊符号的
    时候优先使用单引号引用。

    # badname = "Bozhidar"# goodname = 'Bozhidar'

  • (Option B) Prefer double-quotes unless your string literal
    contains " or escape characters you want to suppress.
    除非你的字符串字面量包含 " 或者你需要抑制转义字符（escape characters）
    优先使用双引号引用。

    # badname = 'Bozhidar'# goodname = "Bozhidar"

  第二种风格可以说在 Ruby 社区更受欢迎些。该指南的字符串字面量，无论如何，
  与第一种风格对齐。

• 不要使用 ?x 符号字面量语法。从 Ruby 1.9 开始基本上它是多余的，?x 将会被解释为 x （只包括一个字符的字符串）。

  # badchar = ?c# goodchar = 'c'

• 别忘了使用 {} 来围绕被插入字符串的实例与全局变量。

  class Person  attr_reader :first_name, :last_name  def initialize(first_name, last_name)    @first_name = first_name    @last_name = last_name  end  # bad - valid, but awkward  def to_s    "#@first_name #@last_name"  end  # good  def to_s    "#{@first_name} #{@last_name}"  endend$global = 0# badputs "$global = #$global"# goodputs "$global = #{$global}"

• 在对象插值的时候不要使用 Object#to_s，它将会被自动调用。

  # badmessage = "This is the #{result.to_s}."# goodmessage = "This is the #{result}."

• 操作较大的字符串时, 避免使用 String#+ 做为替代使用 String#<<。就地级联字符串块总是比 String#+ 更快，它创建了多个字符串对象。

  # good and also fasthtml = ''html << '<h1>Page title</h1>'paragraphs.each do |paragraph|  html << "<p>#{paragraph}</p>"end

• When using heredocs for multi-line strings keep in mind the fact
  that they preserve leading whitespace. It's a good practice to
  employ some margin based on which to trim the excessive whitespace.
  heredocs 中的多行文字会保留前缀空白。因此做好如何缩进的规划。这是一个很好的
  做法，采用一定的边幅在此基础上削减过多的空白。

  code = <<-END.gsub(/^\s+\|/, '')  |def test  |  some_method  |  other_method  |endEND#=> "def test\n  some_method\n  other_method\nend\n"

正则表达式

Some people, when confronted with a problem, think
"I know, I'll use regular expressions." Now they have two problems.<br/>
-- Jamie Zawinski

• 如果只是需要中查找字符串的 text, 不要使用正则表达式：string['text']

• 针对简单的结构, 你可以直接使用string[/RE/]的方式来查询.

  match = string[/regexp/]             # get content of matched regexpfirst_group = string[/text(grp)/, 1] # get content of captured groupstring[/text (grp)/, 1] = 'replace'  # string => 'text replace'

• 当你不需要替结果分组时，使用非分组的群组。

  /(first|second)/   # bad/(?:first|second)/ # good

• 不要使用 Perl 遗风的变量来表示匹配的正则分组（如 $1，$2 等），使用 Regexp.last_match[n] 作为替代。

  /(regexp)/ =~ string...# badprocess $1# goodprocess Regexp.last_match[1]

• 避免使用数字化命名分组很难明白他们代表的意思。命名群组来替代。

  # bad/(regexp)/ =~ string...process Regexp.last_match[1]# good/(?<meaningful_var>regexp)/ =~ string...process meaningful_var

• 字符类有以下几个特殊关键字值得注意: ^, -, \, ], 所以, 不要转义 . 或者 [] 中的括号。

• 注意, ^ 和 $ , 他们匹配行首和行尾, 而不是一个字符串的结尾, 如果你想匹配整个字符串, 用 \A 和 \Z。

  string = "some injection\nusername"string[/^username$/]   # matchesstring[/\Ausername\Z/] # don't match

• 针对复杂的正则表达式，使用 x 修饰符。可提高可读性并可以加入有用的注释。只是要注意空白字符会被忽略。

  regexp = %r{  start         # some text  \s            # white space char  (group)       # first group  (?:alt1|alt2) # some alternation  end}x

• sub/gsub 也支持哈希以及代码块形式语法, 可用于复杂情形下的替换操作.

百分号和字面值

• 需要插值与嵌入双引号的单行字符串使用 %() （是 %Q 的简写）。多行字符串，最好用 heredocs 。

  # bad (no interpolation needed)%(<div class="text">Some text</div>)# should be '<div class="text">Some text</div>'# bad (no double-quotes)%(This is #{quality} style)# should be "This is #{quality} style"# bad (multiple lines)%(<div>\n<span class="big">#{exclamation}</span>\n</div>)# should be a heredoc.# good (requires interpolation, has quotes, single line)%(<tr><td class="name">#{name}</td>)

• 没有 ' 和 " 的字符串不要使用 %q 。除非许多字符需要转义，否则普通字符串可读性更好。

  # badname = %q(Bruce Wayne)time = %q(8 o'clock)question = %q("What did you say?")# goodname = 'Bruce Wayne'time = "8 o'clock"question = '"What did you say?"'

• %r 的方式只适合于定义包含多个 / 符号的正则表达式。

  # bad%r(\s+)# still bad%r(^/(.*)$)# should be /^\/(.*)$/# good%r(^/blog/2011/(.*)$)

• 除非调用的命令中用到了反引号（这种情况不常见），否则不要用 %x。

  # baddate = %x(date)# gooddate = `date`echo = %x(echo `date`)

• 不要用 %s 。社区倾向使用 :"some string" 来创建含有空白的符号。

• 用 % 表示字面量时使用 ()， %r 除外。因为大括号经常出现在正则表达式在很多场景中在很多场景中不太通用的字符例如 { 作为分割符可能是一个更好的选择，取决于正则式的内容。

  # bad%w[one two three]%q{"Test's king!", John said.}# good%w(one two three)%q("Test's king!", John said.)

元编程

• 避免无限循环的元编程。

• 写一个函数库时不要使核心类混乱（不要使用 monkey patch）。

• 代码块形式最好用于字符串插值形式。

  • 当你使用字符串插值形式，总是提供 __FILE__ 和 __LINE__，使得你的回溯有意义。

  class_eval 'def use_relative_model_naming?; true; end', __FILE__, __LINE__

  • define_method 最好用 class_eval{ def ... }

• 当使用 class_eval (或者其他的 eval)以及字符串插值，添加一个注释块使之在插入的时候显示(这是我从 rails 代码学来的实践)：

  # from activesupport/lib/active_support/core_ext/string/output_safety.rbUNSAFE_STRING_METHODS.each do |unsafe_method|  if 'String'.respond_to?(unsafe_method)    class_eval <<-EOT, __FILE__, __LINE__ + 1      def #{unsafe_method}(*args, &block)       # def capitalize(*args, &block)        to_str.#{unsafe_method}(*args, &block)  #   to_str.capitalize(*args, &block)      end                                       # end      def #{unsafe_method}!(*args)              # def capitalize!(*args)        @dirty = true                           #   @dirty = true        super                                   #   super      end                                       # end    EOT  endend

• 避免在元编程中使用 method_missing，它使得回溯变得很麻烦，这个习惯不被列在 #methods，拼写错误的方法可能也在默默的工作，例如 nukes.launch_state = false。考虑使用委托，代理或者是 define_method ，如果必须这样，使用 method_missing ，

  • 确保 也定义了 respond_to_missing?
  • 仅捕捉字首定义良好的方法，像是 find_by_* ― 让你的代码越肯定（assertive）越好。
  • 在语句的最后调用 super
  • delegate 到确定的、非魔法方法中:

  # baddef method_missing?(meth, *args, &block)  if /^find_by_(?<prop>.*)/ =~ meth    # ... lots of code to do a find_by  else    super  endend# gooddef method_missing?(meth, *args, &block)  if /^find_by_(?<prop>.*)/ =~ meth    find_by(prop, *args, &block)  else    super  endend# best of all, though, would to define_method as each findable attribute is declared

杂项

• 总是打开 ruby -w 开关。
• 避免使用哈希作为可选参数。这个方法是不是做太多事了？（对象初始器是本规则的例外）
• 避免一个方法内容超过 10 行代码, 理想情况下, 大多数方法内容应该少于5行。空行不算进 LOC 里。
• 尽量避免方法的参数超过三或四个.
• 有时候, 必须用到全局方法, 应该增加这些方法到 Kernel 模块，并设置他们可见性关键字为 private。

• 尽可能使用类实例变量代替全局变量. (译者注:是类实例变量, 而不是类的实例变量. 汗~~)

  #bad$foo_bar = 1#goodclass Foo  class << self    attr_accessor :bar  endendFoo.bar = 1

• 能够用 alias_method 就不要用 alias。

• 使用 OptionParser 来解析复杂的命令行选项， 琐碎的的命令行，ruby -s 参数即可。

• 优先 Time.now 于 Time.new 当检索当前的系统时间。

• 按照功能来编写方法, 当方法名有意义时, 应该避免方法功能被随意的改变。

• 除非必要, 避免更改已经定义的方法的参数。

• 避免超过三级的代码块嵌套。

• 应该持续性的遵守以上指导方针。

• 多使用（生活）常识。

工具

以下是一些工具，让你自动检查 Ruby 代码是否符合本指南。

RuboCop

RuboCop 是一个基于本指南的 Ruby 代码风格检查工具。 RuboCop 涵盖了本指南相当大的部分，支持 MRI 1.9 和 MRI 2.0，而且与 Emacs 整合良好。

RubyMine

RubyMine 的代码检查是 部分基于 本指南的。

Contributing

Nothing written in this guide is set in stone. It's my desire to work
together with everyone interested in Ruby coding style, so that we could
ultimately create a resource that will be beneficial to the entire Ruby
community.

Feel free to open tickets or send pull requests with improvements. Thanks in
advance for your help!

How to Contribute?

It's easy, just follow the contribution guidelines.

License

This work is licensed under a Creative Commons Attribution 3.0 Unported License

Spread the Word

A community-driven style guide is of little use to a community that
doesn't know about its existence. Tweet about the guide, share it with
your friends and colleagues. Every comment, suggestion or opinion we
get makes the guide just a little bit better. And we want to have the
best possible guide, don't we?

Cheers,<br/>
Bozhidar