03-ruby-syntax/03.11-ruby-style-guide.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Ruby 代码风格"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "(本文来自[Ruby Style Guide](https://github.com/bbatsov/ruby-style-guide))\n",
    "\n",
    "## 序幕\n",
    "\n",
    "> 榜样很重要。<br>\n",
    "> ——墨菲警官《机器战警》\n",
    "\n",
    "身为 Ruby 开发者，有件总是令我烦心的事——Python 开发者有一份好的编程风格参考指南（[PEP-8][PEP-8]）而我们永远没有一份官方指南，一份记录 Ruby 编程风格及最佳实践的指南。我确信风格很重要。我也相信像 Ruby 这样的黑客社区应该可以自己编写这梦寐以求的文档。\n",
    "\n",
    "这份指南开始是作为我们公司内部的 Ruby 编程指南（由我所写的）。后来，我决定把成果贡献给广大的 Ruby 社区，况且这个世界再多一份公司内部文档又有何意义。然而由社区制定及策动的一系列 Ruby 编程实践、惯例及风格确能让世界受益。\n",
    "\n",
    "从编写这份指南开始，我收到了来自世界各地优秀 Ruby 社区的很多用户反馈。衷心感谢所有建议及帮助！同心协力，我们能创造出让每一个 Ruby 开发者受益的资源。\n",
    "\n",
    "顺道一提，如果你对 Rails 感兴趣，你可以看看这份 [Ruby on Rails 风格指南][rails-style-guide]。\n",
    "\n",
    "[PEP-8]: https://www.python.org/dev/peps/pep-0008/\n",
    "[rails-style-guide]: https://github.com/bbatsov/rails-style-guide"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Ruby 风格指南\n",
    "\n",
    "这份 Ruby 风格指南推荐的是 Ruby 的最佳实践，现实世界中的 Ruby 程序员据此可以写出可维护的高质量代码。我们只说实际使用中的用法。指南再好，但里面说的过于理想化结果大家拒绝使用或者可能根本没人用，又有何意义。\n",
    "\n",
    "本指南分为几个小节，每一小节由几条相关的规则构成。我尽力在每条规则后面说明理由（如果省略了说明，那是因为其理由显而易见）。\n",
    "\n",
    "这些规则不是我凭空想象出来的——它们中的绝大部分来自我多年以来作为职业软件工程师的经验，来自 Ruby 社区成员的反馈和建议，以及几个评价甚高的 Ruby 编程资源，像[《Programming Ruby》][pickaxe]以及[《The Ruby Programming Language》][trpl]。\n",
    "\n",
    "Ruby 社区尚未就某些规则达成明显的共识，比如字符串字面量的引号、哈希字面量两端是否应该添加空格、多行链式方法调用中 `.` 操作符的位置。对于这种情况，本指南列出了所有可选的流行风格，你可以任选其一并坚持使用。\n",
    "\n",
    "本指南会一直更新，随着 Ruby 本身的发展，新的规则会添加进来，过时的规则会被剔除。\n",
    "\n",
    "许多项目有其自己的编程风格指南（往往是源于本指南而创建）。当项目的风格指南与本指南发生冲突时，应以项目级的指南为准。\n",
    "\n",
    "你可以使用 [Pandoc][] 生成本指南的 PDF 或 HTML 版本。\n",
    "\n",
    "[RuboCop][] 工具会自动检查你的 Ruby 代码是否符合这份 Ruby 风格指南。\n",
    "\n",
    "本指南有以下翻译版本：\n",
    "\n",
    "* [简体中文](https://github.com/JuanitoFatas/ruby-style-guide/blob/master/README-zhCN.md)\n",
    "* [繁体中文](https://github.com/JuanitoFatas/ruby-style-guide/blob/master/README-zhTW.md)\n",
    "* [法文](https://github.com/gauthier-delacroix/ruby-style-guide/blob/master/README-frFR.md)\n",
    "* [德文](https://github.com/arbox/de-ruby-style-guide/blob/master/README-deDE.md)\n",
    "* [日文](https://github.com/fortissimo1997/ruby-style-guide/blob/japanese/README.ja.md)\n",
    "* [韩文](https://github.com/dalzony/ruby-style-guide/blob/master/README-koKR.md)\n",
    "* [葡萄牙文](https://github.com/rubensmabueno/ruby-style-guide/blob/master/README-PT-BR.md)\n",
    "* [俄文](https://github.com/arbox/ruby-style-guide/blob/master/README-ruRU.md)\n",
    "* [西班牙文](https://github.com/alemohamad/ruby-style-guide/blob/master/README-esLA.md)\n",
    "* [越南文](https://github.com/scrum2b/ruby-style-guide/blob/master/README-viVN.md)\n",
    "\n",
    "[pickaxe]: https://pragprog.com/book/ruby4/programming-ruby-1-9-2-0\n",
    "[trpl]: http://www.amazon.com/Ruby-Programming-Language-David-Flanagan/dp/0596516177\n",
    "[Pandoc]: http://pandoc.org/\n",
    "[RuboCop]: https://github.com/bbatsov/rubocop"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## 目录\n",
    "\n",
    "* [源代码排版](#源代码排版)\n",
    "* [语法](#语法)\n",
    "* [命名](#命名)\n",
    "* [注释](#注释)\n",
    "  * [注解](#注解)\n",
    "  * [Magic Comments](#magic-comments)\n",
    "* [类与模块](#类与模块)\n",
    "* [异常](#异常)\n",
    "* [集合](#集合)\n",
    "* [数值](#数值)\n",
    "* [日期与时间](#日期与时间)\n",
    "* [字符串](#字符串)\n",
    "* [正则表达式](#正则表达式)\n",
    "* [百分号字面量](#百分号字面量)\n",
    "* [元编程](#元编程)\n",
    "* [其他](#其他)\n",
    "* [工具](#工具)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## 源代码排版\n",
    "\n",
    "> 所有风格都又丑又难读，自己的除外。几乎人人都这样想。把“自己的除外”拿掉，他们或许是对的...<br>\n",
    "> ——Jerry Coffin（论缩排）"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### <a name=\"utf-8\"></a> 使用 `UTF-8` 作为源文件的编码。<sup>[[link](#utf-8)]</sup>\n",
    "\n",
    "#### <a name=\"spaces-indentation\"></a> 每个缩排层级使用两个**空格**。不要使用制表符。<sup>[[link](#spaces-indentation)]</sup>\n",
    "\n",
    "```ruby\n",
    "# 差 - 四个空格\n",
    "def some_method\n",
    "  do_something\n",
    "end\n",
    "\n",
    "# 好\n",
    "def some_method\n",
    "do_something\n",
    "end\n",
    "```\n",
    "\n",
    "#### <a name=\"crlf\"></a> 使用 Unix 风格的换行符。<sup>[[link](#crlf)]</sup>\n",
    "\n",
    "（\\*BSD/Solaris/Linux/OS X 系统的用户不需担心，Windows 用户则要格外小心。）\n",
    "\n",
    "* 如果你使用 Git，可用下面这个配置来保护你的项目不被 Windows 的换行符干扰：\n",
    "\n",
    "```bash\n",
    "$ git config --global core.autocrlf true\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### <a name=\"no-semicolon\"></a> 不要使用 `;` 隔开语句与表达式。推论：一行一条语句。<sup>[[link](#no-semicolon)]</sup>\n",
    "\n",
    "```ruby\n",
    "# 差\n",
    "puts 'foobar'; # 不必要的分号\n",
    "\n",
    "puts 'foo'; puts 'bar' # 一行里有两个表达式\n",
    "\n",
    "# 好\n",
    "puts 'foobar'\n",
    "\n",
    "puts 'foo'\n",
    "puts 'bar'\n",
    "\n",
    "puts 'foo', 'bar' # 仅对 puts 适用\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### <a name=\"single-line-classes\"></a> 对于没有主体的类，倾向使用单行定义。<sup>[[link](#single-line-classes)]</sup>\n",
    "\n",
    "```ruby\n",
    "# 差\n",
    "class FooError < StandardError\n",
    "end\n",
    "\n",
    "# 勉强可以\n",
    "class FooError < StandardError; end\n",
    "\n",
    "# 好\n",
    "FooError = Class.new(StandardError)\n",
    "```\n",
    "\n",
    "#### <a name=\"no-single-line-methods\"></a> 定义方法时，避免单行写法。<sup>[[link](#no-single-line-methods)]</sup>\n",
    "\n",
    "尽管这种写法有时颇为普遍，但其略显古怪的定义语法容易使人犯错。无论如何，至少保证单行写法的方法不应该拥有一个以上的表达式。\n",
    "\n",
    "```ruby\n",
    "# 差\n",
    "def too_much; something; something_else; end\n",
    "\n",
    "# 勉强可以 - 注意第一个 ; 是必选的\n",
    "def no_braces_method; body end\n",
    "\n",
    "# 勉强可以 - 注意第二个 ; 是可选的\n",
    "def no_braces_method; body; end\n",
    "\n",
    "# 勉强可以 - 语法正确，但没有 ; 使得可读性欠佳\n",
    "def some_method() body end\n",
    "\n",
    "# 好\n",
    "def some_method\n",
    "body\n",
    "end\n",
    "```\n",
    "\n",
    "这个规则的一个例外是空方法。\n",
    "\n",
    "```ruby\n",
    "# 好\n",
    "def no_op; end\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### <a name=\"spaces-operators\"></a>操作符前后适当地添加空格<sup>[[link](#spaces-operators)]</sup>\n",
    "\n",
    "在逗号 `,`、冒号 `:` 及分号 `;` 之后。尽管 Ruby 解释器（大部分情况下）会忽略空格，但适量的空格可以增强代码的可读性。\n",
    "\n",
    "```ruby\n",
    "sum = 1 + 2\n",
    "a, b = 1, 2\n",
    "class FooError < StandardError; end\n",
    "```\n",
    "\n",
    "（对于操作符）唯一的例外是当使用指数操作符时：\n",
    "\n",
    "```ruby\n",
    "# 差\n",
    "e = M * c ** 2\n",
    "\n",
    "# 好\n",
    "e = M * c**2\n",
    "```\n",
    "  \n",
    "#### <a name=\"spaces-braces\"></a> `(`、`[` 之后，`]`、`)` 之前，不要添加任何空格。在 `{` 前后，在 `}` 之前添加空格。<sup>[[link](#spaces-braces)]</sup>\n",
    "\n",
    "```ruby\n",
    "# 差\n",
    "some( arg ).other\n",
    "[ 1, 2, 3 ].each{|e| puts e}\n",
    "\n",
    "# 好\n",
    "some(arg).other\n",
    "[1, 2, 3].each { |e| puts e }\n",
    "```\n",
    "\n",
    "`{` 与 `}` 需要额外说明，因为它们可以同时用在区块、哈希字面量及字符串插值中。\n",
    "\n",
    "对于哈希字面量，有两种可被接受的风格。第一种风格更具可读性（在 Ruby 社区里似乎更为流行）。第二种风格的优点是，在视觉上使得区块与哈希字面量有所区分。无论你选择何种风格，务必在使用时保持连贯性。\n",
    "\n",
    "```ruby\n",
    "# 好 - { 之后 与 } 之前有空格\n",
    "{ one: 1, two: 2 }\n",
    "\n",
    "# 好 - { 之后 与 } 之前无空格\n",
    "{one: 1, two: 2}\n",
    "```\n",
    "\n",
    "对于插值表达式，括号内两端不要添加空格。\n",
    "\n",
    "```ruby\n",
    "# 差\n",
    "\"From: #{ user.first_name }, #{ user.last_name }\"\n",
    "\n",
    "# 好\n",
    "\"From: #{user.first_name}, #{user.last_name}\"\n",
    "```\n",
    "\n",
    "#### <a name=\"no-space-bang\"></a> `!` 之后，不要添加任何空格。<sup>[[link](#no-space-bang)]</sup>\n",
    "\n",
    "```ruby\n",
    "# 差\n",
    "! something\n",
    "\n",
    "# 好\n",
    "!something\n",
    "```\n",
    "\n",
    "#### <a name=\"no-space-inside-range-literals\"></a>范围的字面量语法中，不要添加任何空格。<sup>[[link](#no-space-inside-range-literals)]</sup>\n",
    "\n",
    "```ruby\n",
    "# 差\n",
    "1 .. 3\n",
    "'a' ... 'z'\n",
    "\n",
    "# 好\n",
    "1..3\n",
    "'a'...'z'\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### <a name=\"indent-when-to-case\"></a> 把 `when` 与 `case` 缩排在同一层级。<sup>[[link](#indent-when-to-case)]</sup>\n",
    "\n",
    "这是《Programming Ruby》与《The Ruby Programming Language》中早已确立的风格。\n",
    "\n",
    "```ruby\n",
    "# 差\n",
    "case\n",
    "  when song.name == 'Misty'\n",
    "    puts 'Not again!'\n",
    "  when song.duration > 120\n",
    "    puts 'Too long!'\n",
    "  when Time.now.hour > 21\n",
    "    puts \"It's too late\"\n",
    "  else\n",
    "    song.play\n",
    "end\n",
    "\n",
    "# 好\n",
    "case\n",
    "when song.name == 'Misty'\n",
    "  puts 'Not again!'\n",
    "when song.duration > 120\n",
    "  puts 'Too long!'\n",
    "when Time.now.hour > 21\n",
    "  puts \"It's too late\"\n",
    "else\n",
    "  song.play\n",
    "end\n",
    "```\n",
    "\n",
    "#### <a name=\"indent-conditional-assignment\"></a>当将一个条件表达式的结果赋值给一个变量时，保持分支缩排在同一层级。<sup>[[link](#indent-conditional-assignment)]</sup>\n",
    "\n",
    "```ruby\n",
    "# 差 - 非常费解\n",
    "kind = case year\n",
    "when 1850..1889 then 'Blues'\n",
    "when 1890..1909 then 'Ragtime'\n",
    "when 1910..1929 then 'New Orleans Jazz'\n",
    "when 1930..1939 then 'Swing'\n",
    "when 1940..1950 then 'Bebop'\n",
    "else 'Jazz'\n",
    "end\n",
    "\n",
    "result = if some_cond\n",
    "  calc_something\n",
    "else\n",
    "  calc_something_else\n",
    "end\n",
    "\n",
    "# 好 - 结构清晰\n",
    "kind = case year\n",
    "       when 1850..1889 then 'Blues'\n",
    "       when 1890..1909 then 'Ragtime'\n",
    "       when 1910..1929 then 'New Orleans Jazz'\n",
    "       when 1930..1939 then 'Swing'\n",
    "       when 1940..1950 then 'Bebop'\n",
    "       else 'Jazz'\n",
    "       end\n",
    "\n",
    "result = if some_cond\n",
    "           calc_something\n",
    "         else\n",
    "           calc_something_else\n",
    "         end\n",
    "\n",
    "# 好 - 并且更好地利用行宽\n",
    "kind =\n",
    "  case year\n",
    "  when 1850..1889 then 'Blues'\n",
    "  when 1890..1909 then 'Ragtime'\n",
    "  when 1910..1929 then 'New Orleans Jazz'\n",
    "  when 1930..1939 then 'Swing'\n",
    "  when 1940..1950 then 'Bebop'\n",
    "  else 'Jazz'\n",
    "  end\n",
    "\n",
    "result =\n",
    "  if some_cond\n",
    "    calc_something\n",
    "  else\n",
    "    calc_something_else\n",
    "  end\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### <a name=\"empty-lines-between-methods\"></a>在各个方法定义之间添加空行，并且将方法分成若干合乎逻辑的段落。<sup>[[link](#empty-lines-between-methods)]</sup>\n",
    "  \n",
    "```ruby\n",
    "def some_method\n",
    "  data = initialize(options)\n",
    "\n",
    "  data.manipulate!\n",
    "\n",
    "  data.result\n",
    "end\n",
    "\n",
    "def some_method\n",
    "  result\n",
    "end\n",
    "```\n",
    "\n",
    "#### <a name=\"two-or-more-empty-lines\"></a>在各个段落之间，使用一个空行分隔。<sup>[[link](#two-or-more-empty-lines)]</sup>\n",
    "  \n",
    "```Ruby\n",
    "# 差 - 使用了两个空行\n",
    "some_method\n",
    "\n",
    "\n",
    "some_method\n",
    "\n",
    "# 好\n",
    "some_method\n",
    "\n",
    "some_method\n",
    "```\n",
    "\n",
    "#### <a name=\"empty-lines-around-access-modifier\"></a>在属性修饰器之后，使用一个空行分隔。<sup>[[link](#empty-lines-around-access-modifier)]</sup>\n",
    "\n",
    "```Ruby\n",
    "# 差\n",
    "class Foo\n",
    "  attr_reader :foo\n",
    "  def foo\n",
    "    # 做一些事情\n",
    "  end\n",
    "end\n",
    "\n",
    "# 好\n",
    "class Foo\n",
    "  attr_reader :foo\n",
    "\n",
    "  def foo\n",
    "    # 做一些事情\n",
    "  end\n",
    "end\n",
    "```\n",
    "\n",
    "#### <a name=\"empty-lines-around-bodies\"></a>在不同缩进的代码之间，不要使用空行分隔。<sup>[[link](#empty-lines-around-bodies)]</sup>\n",
    "  \n",
    "```Ruby\n",
    "# 差\n",
    "class Foo\n",
    "\n",
    "  def foo\n",
    "\n",
    "    begin\n",
    "\n",
    "      do_something do\n",
    "\n",
    "        something\n",
    "\n",
    "      end\n",
    "\n",
    "    rescue\n",
    "\n",
    "      something\n",
    "\n",
    "    end\n",
    "\n",
    "  end\n",
    "\n",
    "end\n",
    "\n",
    "# 好\n",
    "class Foo\n",
    "  def foo\n",
    "    begin\n",
    "      do_something do\n",
    "        something\n",
    "      end\n",
    "    rescue\n",
    "      something\n",
    "    end\n",
    "  end\n",
    "end\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### <a name=\"no-trailing-params-comma\"></a>避免在方法调用的最后一个参数之后添加逗号，尤其当参数没有分布在同一行时。<sup>[[link](#no-trailing-params-comma)]</sup>\n",
    "  \n",
    "```Ruby\n",
    "# 差 - 尽管移动、新增、删除参数颇为方便，但仍不推荐这种写法\n",
    "some_method(\n",
    "  size,\n",
    "  count,\n",
    "  color,\n",
    ")\n",
    "\n",
    "# 差\n",
    "some_method(size, count, color, )\n",
    "\n",
    "# 好\n",
    "some_method(size, count, color)\n",
    "```\n",
    "\n",
    "#### <a name=\"spaces-around-equals\"></a>当给方法的参数赋予默认值时，在 `=` 前后添加空格。<sup>[[link](#spaces-around-equals)]</sup>\n",
    "\n",
    "```Ruby\n",
    "# 差\n",
    "def some_method(arg1=:default, arg2=nil, arg3=[])\n",
    "  # 做一些事情\n",
    "end\n",
    "\n",
    "# 好\n",
    "def some_method(arg1 = :default, arg2 = nil, arg3 = [])\n",
    "  # 做一些事情\n",
    "end\n",
    "```\n",
    "\n",
    "尽管有几本 Ruby 书籍推荐使用第一种风格，但第二种在实践中更为常见（而且似乎更具可读性）。"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### <a name=\"no-trailing-backslash\"></a>避免在非必要的情形下使用续行符 `\\`。<sup>[[link](#no-trailing-backslash)]</sup>\n",
    "\n",
    "在实践中，除了字符串拼接，避免在其他任何地方使用续行。\n",
    "\n",
    "```Ruby\n",
    "# 差\n",
    "result = 1 - \\\n",
    "         2\n",
    "\n",
    "# 好 - 但仍然丑到爆\n",
    "result = 1 \\\n",
    "         - 2\n",
    "\n",
    "long_string = 'First part of the long string' \\\n",
    "              ' and second part of the long string'\n",
    "```\n",
    "\n",
    "#### <a name=\"consistent-multi-line-chains\"></a>使用统一的风格进行多行链式方法调用。<sup>[[link](#consistent-multi-line-chains)]</sup>\n",
    "\n",
    "在 Ruby 社区中存在两种流行的风格：前置 `.`（风格 A）与后置 `.`（风格 B）。\n",
    "\n",
    "* **（风格 A）** 当多行链式方法调用需要另起一行继续时，将 `.` 放在第二行开头。\n",
    "\n",
    "```Ruby\n",
    "# 差 - 需要查看第一行才能理解第二行在做什么\n",
    "one.two.three.\n",
    "  four\n",
    "\n",
    "# 好 - 立刻能够明白第二行在做什么\n",
    "one.two.three\n",
    "  .four\n",
    "```\n",
    "\n",
    "* **（风格 B）** 将 `.` 放在第一行末尾，以表示当前表达式尚未结束。\n",
    "\n",
    "```Ruby\n",
    "# 差 - 需要查看第二行才能知道链式方法调用是否结束\n",
    "one.two.three\n",
    "  .four\n",
    "\n",
    "# 好 - 立刻能够明白第二行还有其他方法调用\n",
    "one.two.three.\n",
    "  four\n",
    "```\n",
    "\n",
    "两种风格各自优点查阅[这里](https://github.com/bbatsov/ruby-style-guide/pull/176)。\n",
    "\n",
    "#### <a name=\"no-double-indent\"></a>当方法调用参数过长时，将它们排列在多行并对齐。<sup>[[link](#no-double-indent)]</sup>\n",
    "  \n",
    "若对齐后长度超过行宽限制，将首个参数位置挪到下一行进行缩排也是可以接受的。\n",
    "\n",
    "\n",
    "```Ruby\n",
    "# 初始（行太长了）\n",
    "def send_mail(source)\n",
    "  Mailer.deliver(to: 'bob@example.com', from: 'us@example.com', subject: 'Important message', body: source.text)\n",
    "end\n",
    "\n",
    "# 差 - 双倍缩排\n",
    "def send_mail(source)\n",
    "  Mailer.deliver(\n",
    "      to: 'bob@example.com',\n",
    "      from: 'us@example.com',\n",
    "      subject: 'Important message',\n",
    "      body: source.text)\n",
    "end\n",
    "\n",
    "# 好\n",
    "def send_mail(source)\n",
    "  Mailer.deliver(to: 'bob@example.com',\n",
    "                 from: 'us@example.com',\n",
    "                 subject: 'Important message',\n",
    "                 body: source.text)\n",
    "end\n",
    "\n",
    "# 好 - 普通缩排\n",
    "def send_mail(source)\n",
    "  Mailer.deliver(\n",
    "    to: 'bob@example.com',\n",
    "    from: 'us@example.com',\n",
    "    subject: 'Important message',\n",
    "    body: source.text\n",
    "  )\n",
    "end\n",
    "```\n",
    "\n",
    "#### <a name=\"align-multiline-arrays\"></a>当构建数组时，若元素跨行，应当保持对齐。<sup>[[link](#align-multiline-arrays)]</sup>\n",
    "\n",
    "```Ruby\n",
    "# 差 - 没有对齐\n",
    "menu_item = ['Spam', 'Spam', 'Spam', 'Spam', 'Spam', 'Spam', 'Spam', 'Spam',\n",
    "  'Baked beans', 'Spam', 'Spam', 'Spam', 'Spam', 'Spam']\n",
    "\n",
    "# 好\n",
    "menu_item = [\n",
    "  'Spam', 'Spam', 'Spam', 'Spam', 'Spam', 'Spam', 'Spam', 'Spam',\n",
    "  'Baked beans', 'Spam', 'Spam', 'Spam', 'Spam', 'Spam'\n",
    "]\n",
    "\n",
    "# 好\n",
    "menu_item =\n",
    "  ['Spam', 'Spam', 'Spam', 'Spam', 'Spam', 'Spam', 'Spam', 'Spam',\n",
    "   'Baked beans', 'Spam', 'Spam', 'Spam', 'Spam', 'Spam']\n",
    "```\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### <a name=\"underscores-in-numerics\"></a>使用 `_` 语法改善大数的数值字面量的可读性。<sup>[[link](#underscores-in-numerics)]</sup>\n",
    "\n",
    "```Ruby\n",
    "# 差 - 有几个零？\n",
    "num = 1000000\n",
    "\n",
    "# 好 - 方便人脑理解\n",
    "num = 1_000_000\n",
    "```\n",
    "\n",
    "#### <a name=\"numeric-literal-prefixes\"></a>当数值需要前缀标识进制时，倾向使用小写字母。<sup>[[link](#numeric-literal-prefixes)]</sup>\n",
    "\n",
    "使用 `0o` 标识八进制，使用 `0x` 标识十六进制，使用 `0b` 标识二进制。十进制数值无需前缀（`0d`）标识。\n",
    "\n",
    "\n",
    "```Ruby\n",
    "# 差\n",
    "num = 01234\n",
    "num = 0O1234\n",
    "num = 0X12AB\n",
    "num = 0B10101\n",
    "num = 0D1234\n",
    "num = 0d1234\n",
    "\n",
    "# 好 - 方便区分数值前缀与具体数字\n",
    "num = 0o1234\n",
    "num = 0x12AB\n",
    "num = 0b10101\n",
    "num = 1234\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### <a name=\"rdoc-conventions\"></a>使用 [RDoc][rdoc] 及其惯例来编写 API 文档。<sup>[[link](#rdoc-conventions)]</sup>\n",
    "\n",
    "注意，不要在注释与 `def` 之间添加空行。\n",
    "\n",
    "#### <a name=\"80-character-limits\"></a>将单行长度控制在 80 个字符内。<sup>[[link](#80-character-limits)]</sup>\n",
    "\n",
    "#### <a name=\"no-trailing-whitespace\"></a>避免行尾空格。<sup>[[link](#no-trailing-whitespace)]</sup>\n",
    "\n",
    "#### <a name=\"newline-eof\"></a>文件以空白行结束。<sup>[[link](#newline-eof)]</sup>\n",
    "\n",
    "#### <a name=\"no-block-comments\"></a>不要使用区块注释。它们不能被空白字符引导，且不如常规注释容易辨认。<sup>[[link](#no-block-comments)]</sup>\n",
    "\n",
    "```Ruby\n",
    "# 差\n",
    "=begin\n",
    "comment line\n",
    "another comment line\n",
    "=end\n",
    "\n",
    "# 好\n",
    "# comment line\n",
    "# another comment line\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## 语法\n",
    "\n",
    "#### <a name=\"double-colons\"></a>使用 `::` 引用常量（包括类与模块）与构造器（比如 `Array()`、`Nokogiri::HTML()`）。不要使用 `::` 调用常规方法。<sup>[[link](#double-colons)]</sup>\n",
    "\n",
    "```ruby\n",
    "# 差\n",
    "SomeClass::some_method\n",
    "some_object::some_method\n",
    "\n",
    "# 好\n",
    "SomeClass.some_method\n",
    "some_object.some_method\n",
    "SomeModule::SomeClass::SOME_CONST\n",
    "SomeModule::SomeClass()\n",
    "```\n",
    "\n",
    "#### <a name=\"method-parens\"></a>使用 `def` 定义方法时，如果有参数则使用括号，如果无参数则省略括号。<sup>[[link](#method-parens)]</sup>\n",
    "\n",
    "```ruby\n",
    "# 差\n",
    "def some_method()\n",
    "  # 省略主体\n",
    "end\n",
    "\n",
    "# 好\n",
    "def some_method\n",
    "  # 省略主体\n",
    "end\n",
    "\n",
    "# 差\n",
    "def some_method_with_parameters param1, param2\n",
    "  # 省略主体\n",
    "end\n",
    "\n",
    "# 好\n",
    "def some_method_with_parameters(param1, param2)\n",
    "  # 省略主体\n",
    "end\n",
    "```\n",
    "\n",
    "#### <a name=\"method-invocation-parens\"></a>方法调用应当使用括号包裹参数，尤其是第一个参数以 `(` 开头时，比如 `f((3 + 2) + 1)`<sup>[[link](#method-invocation-parens)]</sup>\n",
    "\n",
    "```ruby\n",
    "x = Math.sin y  # 差\n",
    "x = Math.sin(y) # 好\n",
    "\n",
    "array.delete e  # 差\n",
    "array.delete(e) # 好\n",
    "\n",
    "temperance = Person.new 'Temperance', 30  # 差\n",
    "temperance = Person.new('Temperance', 30) # 好\n",
    "```\n",
    "\n",
    "但在下述情况下可以省略括号：\n",
    "\n",
    "* 无参调用\n",
    "\n",
    "```ruby\n",
    "# 差\n",
    "Kernel.exit!()\n",
    "2.even?()\n",
    "fork()\n",
    "'test'.upcase()\n",
    "\n",
    "# 好\n",
    "Kernel.exit!\n",
    "2.even?\n",
    "fork\n",
    "'test'.upcase\n",
    "```\n",
    "\n",
    "* 内部 DSL 的组成部分（比如 Rake、Rails、RSpec）\n",
    "\n",
    "```ruby\n",
    "validates(:name, presence: true)  # 差\n",
    "validates :name, presence: true   # 好\n",
    "```\n",
    "\n",
    "* 具有“关键字”特性的方法\n",
    "\n",
    "```Ruby\n",
    "class Person\n",
    "  attr_reader(:name, :age) # 差\n",
    "  attr_reader :name, :age  # 好\n",
    "\n",
    "  # 省略主体\n",
    "end\n",
    "\n",
    "puts(temperance.age) # 差\n",
    "puts temperance.age  # 好\n",
    "```\n",
    "\n",
    "#### <a name=\"optional-arguments\"></a>定义可选参数时，将可选参数放置在参数列表尾部。如果可选参数出现在列表头部，则此方法在调用时可能会产生预期之外的结果。<sup>[[link](#optional-arguments)]</sup>\n",
    "\n",
    "```ruby\n",
    "# 差\n",
    "def some_method(a = 1, b = 2, c, d)\n",
    "  puts \"#{a}, #{b}, #{c}, #{d}\"\n",
    "end\n",
    "\n",
    "some_method('w', 'x') # => '1, 2, w, x'\n",
    "some_method('w', 'x', 'y') # => 'w, 2, x, y'\n",
    "some_method('w', 'x', 'y', 'z') # => 'w, x, y, z'\n",
    "\n",
    "# 好\n",
    "def some_method(c, d, a = 1, b = 2)\n",
    "  puts \"#{a}, #{b}, #{c}, #{d}\"\n",
    "end\n",
    "\n",
    "some_method('w', 'x') # => '1, 2, w, x'\n",
    "some_method('w', 'x', 'y') # => 'y, 2, w, x'\n",
    "some_method('w', 'x', 'y', 'z') # => 'y, z, w, x'\n",
    "```\n",
    "\n",
    "#### <a name=\"parallel-assignment\"></a>定义变量时，避免并行赋值。<sup>[[link](#parallel-assignment)]</sup>\n",
    "  \n",
    "但当右值为方法调用返回值，或是与 `*` 操作符配合使用，或是交换两个变量的值，并行赋值也是可以接受的。并行赋值的可读性通常不如分开赋值。\n",
    "\n",
    "\n",
    "```ruby\n",
    "# 差\n",
    "a, b, c, d = 'foo', 'bar', 'baz', 'foobar'\n",
    "\n",
    "# 好\n",
    "a = 'foo'\n",
    "b = 'bar'\n",
    "c = 'baz'\n",
    "d = 'foobar'\n",
    "\n",
    "# 好 - 交换两个变量的值\n",
    "a = 'foo'\n",
    "b = 'bar'\n",
    "\n",
    "a, b = b, a\n",
    "puts a # => 'bar'\n",
    "puts b # => 'foo'\n",
    "\n",
    "# 好 - 右值为方法调用返回值\n",
    "def multi_return\n",
    "  [1, 2]\n",
    "end\n",
    "\n",
    "first, second = multi_return\n",
    "\n",
    "# 好 - 与 * 操作符配合使用\n",
    "first, *list = [1, 2, 3, 4] # first => 1, list => [2, 3, 4]\n",
    "\n",
    "hello_array = *'Hello' # => [\"Hello\"]\n",
    "\n",
    "a = *(1..3) # => [1, 2, 3]\n",
    "```\n",
    "\n",
    "#### <a name=\"trailing-underscore-variables\"></a>除非必要，否则避免在并行赋值时使用单字符的 `_` 变量。<sup>[[link]](#trailing-underscore-variables)</sup>\n",
    "\n",
    "优先考虑前缀形式的下划线变量，而不是直接使用 `_`，因为前者可以提供一定的语义信息。但当赋值语句左侧出现带 `*` 操作符的变量时，使用 `_` 也是可以接受的。\n",
    "\n",
    "```ruby\n",
    "foo = 'one,two,three,four,five'\n",
    "\n",
    "# 差 - 可有可无，且无任何有用信息\n",
    "first, second, _ = foo.split(',')\n",
    "first, _, _ = foo.split(',')\n",
    "first, *_ = foo.split(',')\n",
    "\n",
    "# 好\n",
    "a, = foo.split(',')\n",
    "a, b, = foo.split(',')\n",
    "\n",
    "# 好 - 可有可无，但提供了额外信息\n",
    "first, _second = foo.split(',')\n",
    "first, _second, = foo.split(',')\n",
    "first, *_ending = foo.split(',')\n",
    "\n",
    "# 好 - 占位符，_ 担当最后一个元素\n",
    "*beginning, _ = foo.split(',')\n",
    "*beginning, something, _ = foo.split(',')\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### <a name=\"no-for-loops\"></a> 永远不要使用 `for`， 除非你很清楚为什么。<sup>[[link](#no-for-loops)]</sup>\n",
    "\n",
    "大部分情况下，你应该使用迭代器。`for` 是由 `each` 实现的，所以你绕弯了。另外，`for` 没有引入一个新的作用域 (`each` 有），因此在它内部定义的变量在外部仍是可见的。\n",
    "\n",
    "```ruby\n",
    "arr = [1, 2, 3]\n",
    "\n",
    "# 差\n",
    "for elem in arr do\n",
    "  puts elem\n",
    "end\n",
    "\n",
    "# 注意，elem 可在 for 循环外部被访问\n",
    "elem # => 3\n",
    "\n",
    "# 好\n",
    "arr.each { |elem| puts elem }\n",
    "\n",
    "# 注意，elem 不可在 each 块外部被访问\n",
    "elem # => NameError: undefined local variable or method `elem'\n",
    "```\n",
    "\n",
    "#### <a name=\"no-then\"></a>永远不要在多行 `if`/`unless` 中使用 `then`。<sup>[[link](#no-then)]</sup>\n",
    "\n",
    "```ruby\n",
    "# 差\n",
    "if some_condition then\n",
    "  # 省略主体\n",
    "end\n",
    "\n",
    "# 好\n",
    "if some_condition\n",
    "  # 省略主体\n",
    "end\n",
    "```\n",
    "\n",
    "#### <a name=\"same-line-condition\"></a>在多行 `if/unless` 中，总是把条件表达式与 `if/unless` 放置在同一行。<sup>[[link](#same-line-condition)]</sup>\n",
    "\n",
    "```ruby\n",
    "# 差\n",
    "if\n",
    "  some_condition\n",
    "  do_something\n",
    "  do_something_else\n",
    "end\n",
    "\n",
    "# 好\n",
    "if some_condition\n",
    "  do_something\n",
    "  do_something_else\n",
    "end\n",
    "```\n",
    "\n",
    "#### <a name=\"ternary-operator\"></a>倾向使用三元操作符（`?:`）而不是 `if/then/else/end` 结构。前者更为常见且简练。<sup>[[link](#ternary-operator)]</sup>\n",
    "\n",
    "```ruby\n",
    "# 差\n",
    "result = if some_condition then something else something_else end\n",
    "\n",
    "# 好\n",
    "result = some_condition ? something : something_else\n",
    "```\n",
    "\n",
    "#### <a name=\"no-nested-ternary\"></a>三元操作符的每个分支只写一个表达式。即不要嵌套三元操作符。嵌套情况请使用 `if/else` 结构。<sup>[[link](#no-nested-ternary)]</sup>\n",
    "\n",
    "```ruby\n",
    "# 差\n",
    "some_condition ? (nested_condition ? nested_something : nested_something_else) : something_else\n",
    "\n",
    "# 好\n",
    "if some_condition\n",
    "  nested_condition ? nested_something : nested_something_else\n",
    "else\n",
    "  something_else\n",
    "end\n",
    "```\n",
    "\n",
    "#### <a name=\"no-semicolon-ifs\"></a>永远不要使用 `if x; ...`。使用三元操作符来替代。<sup>[[link](#no-semicolon-ifs)]</sup>\n",
    "\n",
    "```ruby\n",
    "# 差\n",
    "result = if some_condition; something else something_else end\n",
    "\n",
    "# 好\n",
    "result = some_condition ? something : something_else\n",
    "```\n",
    "\n",
    "#### <a name=\"use-if-case-returns\"></a>利用“`if` 与 `case` 是表达式”的这个特性。<sup>[[link](#use-if-case-returns)]</sup>\n",
    "\n",
    "```ruby\n",
    "# 差\n",
    "if condition\n",
    "  result = x\n",
    "else\n",
    "  result = y\n",
    "end\n",
    "\n",
    "# 好\n",
    "result =\n",
    "  if condition\n",
    "    x\n",
    "  else\n",
    "    y\n",
    "  end\n",
    "```\n",
    "\n",
    "#### <a name=\"one-line-cases\"></a>在 `case` 表达式中，单行情况使用 `when x then ...` 语法。另一种语法 `when x: ...` 在 Ruby 1.9 之后被移除了。<sup>[[link](#one-line-cases)]</sup>\n",
    "\n",
    "#### <a name=\"no-when-semicolons\"></a>不要使用 `when x; ...` 语法。参考前一条规则。<sup>[[link](#no-when-semicolons)]</sup>\n",
    "\n",
    "#### <a name=\"bang-not-not\"></a>使用 `!` 而不是 `not`。<sup>[[link](#bang-not-not)]</sup>\n",
    "\n",
    "```ruby\n",
    "# 差 - 因为操作符的优先级，这里必须使用括号\n",
    "x = (not something)\n",
    "\n",
    "# 好\n",
    "x = !something\n",
    "```\n",
    "\n",
    "#### <a name=\"no-bang-bang\"></a>避免使用 `!!`。<sup>[[link](#no-bang-bang)]</sup>\n",
    "\n",
    "`!!` 会将表达式结果转换为布尔值，但对于流程控制的表达式通常并不需要如此显式的转换过程。如果需要做 `nil` 检查，那么调用对象的 `nil?` 方法。\n",
    "\n",
    "```ruby\n",
    "# 差\n",
    "x = 'test'\n",
    "# 令人费解的 nil 检查\n",
    "if !!x\n",
    "  # 省略主体\n",
    "end\n",
    "\n",
    "# 好\n",
    "x = 'test'\n",
    "if x\n",
    "  # 省略主体\n",
    "end\n",
    "```\n",
    "\n",
    "#### <a name=\"no-and-or-or\"></a>永远不要使用 `and` 与 `or` 关键字。使用 `&&` 与 `||` 来替代。<sup>[[link](#no-and-or-or)]</sup>\n",
    "\n",
    "```ruby\n",
    "# 差\n",
    "# 布尔表达式\n",
    "ok = got_needed_arguments and arguments_are_valid\n",
    "\n",
    "# 流程控制\n",
    "document.save or fail(RuntimeError, \"Failed to save document!\")\n",
    "\n",
    "# 好\n",
    "# 布尔表达式\n",
    "ok = got_needed_arguments && arguments_are_valid\n",
    "\n",
    "# 流程控制\n",
    "fail(RuntimeError, \"Failed to save document!\") unless document.save\n",
    "\n",
    "# 流程控制\n",
    "document.save || fail(RuntimeError, \"Failed to save document!\")\n",
    "```\n",
    "\n",
    "#### <a name=\"no-multiline-ternary\"></a>避免使用多行三元操作符（`?:`）。使用 `if`/`unless` 来替代。<sup>[[link](#no-multiline-ternary)]</sup>\n",
    "\n",
    "#### <a name=\"if-as-a-modifier\"></a>对于单行主体，倾向使用 `if`/`unless` 修饰语法。另一种方法是使用流程控制 `&&`/`||`。<sup>[[link](#if-as-a-modifier)]</sup>\n",
    "\n",
    "```ruby\n",
    "# 差\n",
    "if some_condition\n",
    "  do_something\n",
    "end\n",
    "\n",
    "# 好\n",
    "do_something if some_condition\n",
    "\n",
    "# 好 - 使用流程控制\n",
    "some_condition && do_something\n",
    "```\n",
    "\n",
    "#### <a name=\"no-multiline-if-modifiers\"></a>避免在多行区块后使用 `if`/`unless` 修饰语法。<sup>[[link](#no-multiline-if-modifiers)]</sup>\n",
    "\n",
    "```ruby\n",
    "# 差\n",
    "10.times do\n",
    "  # 省略多行主体\n",
    "end if some_condition\n",
    "\n",
    "# 好\n",
    "if some_condition\n",
    "  10.times do\n",
    "    # 省略多行主体\n",
    "  end\n",
    "end\n",
    "```\n",
    "\n",
    "#### <a name=\"no-nested-modifiers\"></a>避免使用嵌套 `if`/`unless`/`while`/`until` 修饰语法。适当情况下，使用 `&&`/`||` 来替代。<sup>[[link](#no-nested-modifiers)]</sup>\n",
    "\n",
    "```ruby\n",
    "# 差\n",
    "do_something if other_condition if some_condition\n",
    "\n",
    "# 好\n",
    "do_something if some_condition && other_condition\n",
    "```\n",
    "\n",
    "#### <a name=\"unless-for-negatives\"></a>对于否定条件，倾向使用 `unless` 而不是 `if`（或是使用流程控制 `||`）。<sup>[[link](#unless-for-negatives)]</sup>\n",
    "\n",
    "```ruby\n",
    "# 差\n",
    "do_something if !some_condition\n",
    "\n",
    "# 差\n",
    "do_something if not some_condition\n",
    "\n",
    "# 好\n",
    "do_something unless some_condition\n",
    "\n",
    "# 好\n",
    "some_condition || do_something\n",
    "```\n",
    "\n",
    "#### <a name=\"no-else-with-unless\"></a>不要使用 `unless` 与 `else` 的组合。将它们改写成肯定条件。<sup>[[link](#no-else-with-unless)]</sup>\n",
    "\n",
    "```ruby\n",
    "# 差\n",
    "unless success?\n",
    "  puts 'failure'\n",
    "else\n",
    "  puts 'success'\n",
    "end\n",
    "\n",
    "# 好\n",
    "if success?\n",
    "  puts 'success'\n",
    "else\n",
    "  puts 'failure'\n",
    "end\n",
    "```\n",
    "\n",
    "#### <a name=\"no-parens-around-condition\"></a>不要使用括号包裹流程控制中的条件表达式。<sup>[[link](#no-parens-around-condition)]</sup>\n",
    "\n",
    "```ruby\n",
    "# 差\n",
    "if (x > 10)\n",
    "  # 省略主体\n",
    "end\n",
    "\n",
    "# 好\n",
    "if x > 10\n",
    "  # 省略主体\n",
    "end\n",
    "```\n",
    "\n",
    "这个规则的一个例外是[条件表达式中的安全赋值](#safe-assignment-in-condition)。"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### <a name=\"no-multiline-while-do\"></a>在多行 `while/until` 中，不要使用 `while/until condition do`。<sup>[[link](#no-multiline-while-do)]</sup>\n",
    "\n",
    "```ruby\n",
    "# 差\n",
    "while x > 5 do\n",
    "  # 省略主体\n",
    "end\n",
    "\n",
    "until x > 5 do\n",
    "  # 省略主体\n",
    "end\n",
    "\n",
    "# 好\n",
    "while x > 5\n",
    "  # 省略主体\n",
    "end\n",
    "\n",
    "until x > 5\n",
    "  # 省略主体\n",
    "end\n",
    "```\n",
    "\n",
    "#### <a name=\"while-as-a-modifier\"></a>对于单行主体，倾向使用 `while/until` 修饰语法。<sup>[[link](#while-as-a-modifier)]</sup>\n",
    "\n",
    "```ruby\n",
    "# 差\n",
    "while some_condition\n",
    "  do_something\n",
    "end\n",
    "\n",
    "# 好\n",
    "do_something while some_condition\n",
    "```\n",
    "\n",
    "#### <a name=\"until-for-negatives\"></a>对于否定条件，倾向使用 `until` 而不是 `while`。<sup>[[link](#until-for-negatives)]</sup>\n",
    "\n",
    "```ruby\n",
    "# 差\n",
    "do_something while !some_condition\n",
    "\n",
    "# 好\n",
    "do_something until some_condition\n",
    "```\n",
    "\n",
    "#### <a name=\"infinite-loop\"></a>对于无限循环，使用 `Kernel#loop` 而不是 `while/until`。<sup>[[link](#infinite-loop)]</sup>\n",
    "\n",
    "```ruby\n",
    "# 差\n",
    "while true\n",
    "  do_something\n",
    "end\n",
    "\n",
    "until false\n",
    "  do_something\n",
    "end\n",
    "\n",
    "# 好\n",
    "loop do\n",
    "  do_something\n",
    "end\n",
    "```\n",
    "\n",
    "#### <a name=\"loop-with-break\"></a>对于后置条件循环语句，倾向使用 `Kernel#loop` 与 `break` 的组合，而不是 `begin/end/until` 或 `begin/end/while`。<sup>[[link](#loop-with-break)]</sup>\n",
    "\n",
    "```ruby\n",
    "# 差\n",
    "begin\n",
    "  puts val\n",
    "  val += 1\n",
    "end while val < 0\n",
    "\n",
    "# 好\n",
    "loop do\n",
    "  puts val\n",
    "  val += 1\n",
    "  break unless val < 0\n",
    "end\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### <a name=\"no-braces-opts-hash\"></a>对于可选参数的哈希，省略其外围的花括号。<sup>[[link](#no-braces-opts-hash)]</sup>\n",
    "\n",
    "```ruby\n",
    "# 差\n",
    "user.set({ name: 'John', age: 45, permissions: { read: true } })\n",
    "\n",
    "# 好\n",
    "user.set(name: 'John', age: 45, permissions: { read: true })\n",
    "```\n",
    "\n",
    "#### <a name=\"no-dsl-decorating\"></a>对于 DSL 的内部方法调用，同时省略其外围的圆括号与花括号。<sup>[[link](#no-dsl-decorating)]</sup>\n",
    "\n",
    "```ruby\n",
    "class Person < ActiveRecord::Base\n",
    "  # 差\n",
    "  validates(:name, { presence: true, length: { within: 1..10 } })\n",
    "\n",
    "  # 好\n",
    "  validates :name, presence: true, length: { within: 1..10 }\n",
    "end\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### <a name=\"single-action-blocks\"></a>当被调用方法是当前区块中唯一操作时，倾向使用简短的传参语法。<sup>[[link](#single-action-blocks)]</sup>\n",
    "\n",
    "```ruby\n",
    "# 差\n",
    "names.map { |name| name.upcase }\n",
    "\n",
    "# 好\n",
    "names.map(&:upcase)\n",
    "```\n",
    "\n",
    "#### <a name=\"single-line-blocks\"></a>对于单行主体，倾向使用 `{...}` 而不是 `do...end`。对于多行主体，避免使用 `{...}`。对于“流程控制”或“方法定义”（比如 Rakefile、其他 DSL 构成片段），总是使用 `do...end`。避免在链式方法调用中使用 `do...end`。<sup>[[link](#single-line-blocks)]</sup>\n",
    "\n",
    "```ruby\n",
    "names = %w[Bozhidar Steve Sarah]\n",
    "\n",
    "# 差\n",
    "names.each do |name|\n",
    "  puts name\n",
    "end\n",
    "\n",
    "# 好\n",
    "names.each { |name| puts name }\n",
    "\n",
    "# 差\n",
    "names.select do |name|\n",
    "  name.start_with?('S')\n",
    "end.map { |name| name.upcase }\n",
    "\n",
    "# 好\n",
    "names.select { |name| name.start_with?('S') }.map(&:upcase)\n",
    "```\n",
    "\n",
    "某些人可能会争论在多行链式方法调用时使用 `{...}` 看起来还可以。但他们应该扪心自问——这样的代码真的可读吗？难道不能把区块内容提取出来放到小巧的方法里吗？\n",
    "\n",
    "#### <a name=\"block-argument\"></a>优先考虑使用显式区块参数，以避免某些情况下通过创建区块的手法来传递参数给其他区块。此规则对性能有所影响，因为区块会被转换为 `Proc` 对象。<sup>[[link](#block-argument)]</sup>\n",
    "\n",
    "```ruby\n",
    "require 'tempfile'\n",
    "\n",
    "# 差\n",
    "def with_tmp_dir\n",
    "  Dir.mktmpdir do |tmp_dir|\n",
    "    Dir.chdir(tmp_dir) { |dir| yield dir }  # 通过创建区块的手法来传递参数\n",
    "  end\n",
    "end\n",
    "\n",
    "# 好\n",
    "def with_tmp_dir(&block)\n",
    "  Dir.mktmpdir do |tmp_dir|\n",
    "    Dir.chdir(tmp_dir, &block)\n",
    "  end\n",
    "end\n",
    "\n",
    "with_tmp_dir do |dir|\n",
    "  puts \"dir is accessible as a parameter and pwd is set: #{dir}\"\n",
    "end\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### <a name=\"no-explicit-return\"></a>避免在不需要流程控制的情况下使用 `return`。<sup>[[link](#no-explicit-return)]</sup>\n",
    "\n",
    "```ruby\n",
    "# 差\n",
    "def some_method(some_arr)\n",
    "  return some_arr.size\n",
    "end\n",
    "\n",
    "# 好\n",
    "def some_method(some_arr)\n",
    "  some_arr.size\n",
    "end\n",
    "```\n",
    "\n",
    "#### <a name=\"no-self-unless-required\"></a>避免在不需要的情况下使用 `self`。（只有在调用 `self` 的修改器、以保留字命名的方法、重载的运算符时才需要）<sup>[[link](#no-self-unless-required)]</sup>\n",
    "\n",
    "```ruby\n",
    "# 差\n",
    "def ready?\n",
    "  if self.last_reviewed_at > self.last_updated_at\n",
    "    self.worker.update(self.content, self.options)\n",
    "    self.status = :in_progress\n",
    "  end\n",
    "  self.status == :verified\n",
    "end\n",
    "\n",
    "# 好\n",
    "def ready?\n",
    "  if last_reviewed_at > last_updated_at\n",
    "    worker.update(content, options)\n",
    "    self.status = :in_progress\n",
    "  end\n",
    "  status == :verified\n",
    "end\n",
    "```\n",
    "\n",
    "#### <a name=\"no-shadowing\"></a>避免局部变量遮蔽方法调用，除非它们具有相同效果。<sup>[[link](#no-shadowing)]</sup>\n",
    "\n",
    "```ruby\n",
    "class Foo\n",
    "  attr_accessor :options\n",
    "\n",
    "  # 勉强可以\n",
    "  def initialize(options)\n",
    "    self.options = options\n",
    "    # 此处 self.options 与 options 具有相同效果\n",
    "  end\n",
    "\n",
    "  # 差\n",
    "  def do_something(options = {})\n",
    "    unless options[:when] == :later\n",
    "      output(self.options[:message])\n",
    "    end\n",
    "  end\n",
    "\n",
    "  # 好\n",
    "  def do_something(params = {})\n",
    "    unless params[:when] == :later\n",
    "      output(options[:message])\n",
    "    end\n",
    "  end\n",
    "end\n",
    "```\n",
    "\n",
    "#### <a name=\"safe-assignment-in-condition\"></a>不要在条件表达式中使用 `=`（赋值语句）的返回值，除非赋值语句包裹在括号之中。这种惯用法被称作**条件表达式中的安全赋值**。<sup>[[link](#safe-assignment-in-condition)]</sup>\n",
    "\n",
    "```ruby\n",
    "# 差 - 会出现警告\n",
    "if v = array.grep(/foo/)\n",
    "  do_something(v)\n",
    "  ...\n",
    "end\n",
    "\n",
    "# 好 - 尽管 Ruby 解释器仍会出现警告，但 RuboCop 不会\n",
    "if (v = array.grep(/foo/))\n",
    "  do_something(v)\n",
    "  ...\n",
    "end\n",
    "\n",
    "# 好\n",
    "v = array.grep(/foo/)\n",
    "if v\n",
    "  do_something(v)\n",
    "  ...\n",
    "end\n",
    "```\n",
    "\n",
    "#### <a name=\"self-assignment\"></a>优先考虑简短的自我赋值语法。<sup>[[link](#self-assignment)]</sup>\n",
    "\n",
    "```ruby\n",
    "# 差\n",
    "x = x + y\n",
    "x = x * y\n",
    "x = x**y\n",
    "x = x / y\n",
    "x = x || y\n",
    "x = x && y\n",
    "\n",
    "# 好\n",
    "x += y\n",
    "x *= y\n",
    "x **= y\n",
    "x /= y\n",
    "x ||= y\n",
    "x &&= y\n",
    "```\n",
    "\n",
    "#### <a name=\"double-pipe-for-uninit\"></a>当变量尚未初始化时，使用 `||=` 对其进行初始化。<sup>[[link](#double-pipe-for-uninit)]</sup>\n",
    "\n",
    "```ruby\n",
    "# 差\n",
    "name = name ? name : 'Bozhidar'\n",
    "\n",
    "# 差\n",
    "name = 'Bozhidar' unless name\n",
    "\n",
    "# 好 - 当且仅当 name 为 nil 或 false 时，设置 name 的值为 'Bozhidar'\n",
    "name ||= 'Bozhidar'\n",
    "```\n",
    "\n",
    "#### <a name=\"no-double-pipes-for-bools\"></a>不要使用 `||=` 对布尔变量进行初始化。<sup>[[link](#no-double-pipes-for-bools)]</sup>\n",
    "\n",
    "```ruby\n",
    "# 差 - 设置 enabled 的值为 true，即使其原本的值是 false\n",
    "enabled ||= true\n",
    "\n",
    "# 好\n",
    "enabled = true if enabled.nil?\n",
    "```\n",
    "\n",
    "#### <a name=\"double-amper-preprocess\"></a>使用 `&&=` 预先检查变量是否存在，如果存在，则做相应动作。使用 `&&=` 语法可以省去 `if` 检查。<sup>[[link](#double-amper-preprocess)]</sup>\n",
    "\n",
    "```ruby\n",
    "# 差\n",
    "if something\n",
    "  something = something.downcase\n",
    "end\n",
    "\n",
    "# 差\n",
    "something = something ? something.downcase : nil\n",
    "\n",
    "# 勉强可以\n",
    "something = something.downcase if something\n",
    "\n",
    "# 好\n",
    "something = something && something.downcase\n",
    "\n",
    "# 更好\n",
    "something &&= something.downcase\n",
    "```\n",
    "\n",
    "#### <a name=\"no-case-equality\"></a>避免使用 `case` 语句等价操作符 `===`。从名称可知，这是 `case` 语句隐式使用的操作符，在 `case` 语句外的场合中使用，会产生难以理解的代码。<sup>[[link](#no-case-equality)]</sup>\n",
    "\n",
    "```ruby\n",
    "# 差\n",
    "Array === something\n",
    "(1..100) === 7\n",
    "/something/ === some_string\n",
    "\n",
    "# 好\n",
    "something.is_a?(Array)\n",
    "(1..100).include?(7)\n",
    "some_string =~ /something/\n",
    "```\n",
    "\n",
    "#### <a name=\"eql\"></a>能使用 `==` 就不要使用 `eql?`。提供更加严格比较的 `eql?` 在实践中极少使用。<sup>[[link](#eql)]</sup>\n",
    "\n",
    "```ruby\n",
    "# 差 - 对于字符串，eql? 与 == 具有相同效果\n",
    "'ruby'.eql? some_str\n",
    "\n",
    "# 好\n",
    "'ruby' == some_str\n",
    "1.0.eql? x # 当需要区别 Fixnum 1 与 Float 1.0 时，eql? 是具有意义的\n",
    "```\n",
    "\n",
    "#### <a name=\"no-cryptic-perlisms\"></a>避免使用 Perl 风格的特殊变量（比如 `$:`、`$;` 等）。它们看起来非常神秘，但除了单行脚本，其他情况并不鼓励使用。建议使用 `English` 程序库提供的友好别名。<sup>[[link](#no-cryptic-perlisms)]</sup>\n",
    "\n",
    "```ruby\n",
    "# 差\n",
    "$:.unshift File.dirname(__FILE__)\n",
    "\n",
    "# 好\n",
    "require 'English'\n",
    "$LOAD_PATH.unshift File.dirname(__FILE__)\n",
    "```\n",
    "\n",
    "#### <a name=\"parens-no-spaces\"></a>永远不要在方法名与左括号之间添加空格。<sup>[[link](#parens-no-spaces)]</sup>\n",
    "\n",
    "```ruby\n",
    "# 差\n",
    "f (3 + 2) + 1\n",
    "\n",
    "# 好\n",
    "f(3 + 2) + 1\n",
    "```\n",
    "\n",
    "#### <a name=\"always-warn-at-runtime\"></a>运行 Ruby 解释器时，总是开启 `-w` 选项来。如果你忘了某个上述某个规则，它就会警告你！<sup>[[link](#always-warn-at-runtime)]</sup>\n",
    "\n",
    "#### <a name=\"no-nested-methods\"></a>不要在方法中嵌套定义方法，使用 lambda 方法来替代。<sup>[[link](#no-nested-methods)]</sup>\n",
    "\n",
    "嵌套定义产生的方法，事实上和外围方法处于同一作用域（比如类作用域）。此外，“嵌套方法”会在定义它的外围方法每次调用时被重新定义。\n",
    "\n",
    "```ruby\n",
    "# 差\n",
    "def foo(x)\n",
    "  def bar(y)\n",
    "    # 省略主体\n",
    "  end\n",
    "\n",
    "  bar(x)\n",
    "end\n",
    "\n",
    "# 好 - 作用同前，但 bar 不会在 foo 每次调用时被重新定义\n",
    "def bar(y)\n",
    "  # 省略主体\n",
    "end\n",
    "\n",
    "def foo(x)\n",
    "  bar(x)\n",
    "end\n",
    "\n",
    "# 好\n",
    "def foo(x)\n",
    "  bar = ->(y) { ... }\n",
    "  bar.call(x)\n",
    "end\n",
    "```\n",
    "\n",
    "#### <a name=\"lambda-multi-line\"></a>对于单行区块，使用新的 lambda 字面量定义语法。对于多行区块，使用 `lambda` 定义语法。<sup>[[link](#lambda-multi-line)]</sup>\n",
    "\n",
    "```ruby\n",
    "# 差\n",
    "l = lambda { |a, b| a + b }\n",
    "l.call(1, 2)\n",
    "\n",
    "# 好 - 但看起来怪怪的\n",
    "l = ->(a, b) do\n",
    "  tmp = a * 7\n",
    "  tmp * b / 50\n",
    "end\n",
    "\n",
    "# 好\n",
    "l = ->(a, b) { a + b }\n",
    "l.call(1, 2)\n",
    "\n",
    "l = lambda do |a, b|\n",
    "  tmp = a * 7\n",
    "  tmp * b / 50\n",
    "end\n",
    "```\n",
    "\n",
    "#### <a name=\"stabby-lambda-with-args\"></a>定义 lambda 方法时，如果有参数则使用括号。<sup>[[link](#stabby-lambda-with-args)]</sup>\n",
    "\n",
    "```ruby\n",
    "# 差\n",
    "l = ->x, y { something(x, y) }\n",
    "\n",
    "# 好\n",
    "l = ->(x, y) { something(x, y) }\n",
    "```\n",
    "\n",
    "#### <a name=\"stabby-lambda-no-args\"></a>定义 lambda 方法时，如果无参数则省略括号。<sup>[[link](#stabby-lambda-no-args)]</sup>\n",
    "\n",
    "```ruby\n",
    "# 差\n",
    "l = ->() { something }\n",
    "\n",
    "# 好\n",
    "l = -> { something }\n",
    "```\n",
    "\n",
    "#### <a name=\"proc\"></a>倾向使用 `proc` 而不是 `Proc.new`。<sup>[[link](#proc)]</sup>\n",
    "\n",
    "```ruby\n",
    "# 差\n",
    "p = Proc.new { |n| puts n }\n",
    "\n",
    "# 好\n",
    "p = proc { |n| puts n }\n",
    "```\n",
    "\n",
    "#### <a name=\"proc-call\"></a>对于 lambda 方法或代码块，倾向使用 `proc.call()` 而不是 `proc[]` 或 `proc.()`。<sup>[[link](#proc-call)]</sup>\n",
    "\n",
    "```ruby\n",
    "# 差 - 看上去像是枚举器的存取操作\n",
    "l = ->(v) { puts v }\n",
    "l[1]\n",
    "\n",
    "# 差 - 极少见的调用语法\n",
    "l = ->(v) { puts v }\n",
    "l.(1)\n",
    "\n",
    "# 好\n",
    "l = ->(v) { puts v }\n",
    "l.call(1)\n",
    "```\n",
    "\n",
    "#### <a name=\"underscore-unused-vars\"></a>未被使用的区块参数或局部变量，添加 `_` 前缀或直接使用 `_`（尽管表意性略差）。这种做法可以抑制 Ruby 解释器或 RuboCop 等工具发出“变量尚未使用”的警告。<sup>[[link](#underscore-unused-vars)]</sup>\n",
    "\n",
    "```ruby\n",
    "# 差\n",
    "result = hash.map { |k, v| v + 1 }\n",
    "\n",
    "def something(x)\n",
    "  unused_var, used_var = something_else(x)\n",
    "  # ...\n",
    "end\n",
    "\n",
    "# 好\n",
    "result = hash.map { |_k, v| v + 1 }\n",
    "\n",
    "def something(x)\n",
    "  _unused_var, used_var = something_else(x)\n",
    "  # ...\n",
    "end\n",
    "\n",
    "# 好\n",
    "result = hash.map { |_, v| v + 1 }\n",
    "\n",
    "def something(x)\n",
    "  _, used_var = something_else(x)\n",
    "  # ...\n",
    "end\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### <a name=\"global-stdout\"></a>使用 `$stdout/$stderr/$stdin` 而不是 `STDOUT/STDERR/STDIN`。`STDOUT/STDERR/STDIN` 是常量，尽管在 Ruby 中允许给常量重新赋值（可能是重定向某些流），但解释器会发出警告。<sup>[[link](#global-stdout)]</sup>\n",
    "\n",
    "#### <a name=\"warn\"></a>使用 `warn` 而不是 `$stderr.puts`。除了更加简练清晰外，`warn` 允许你在需要时通过设置解释器选项（使用 `-W0` 将警告级别设置为 0）来抑制警告。<sup>[[link](#warn)]</sup>\n",
    "\n",
    "#### <a name=\"sprintf\"></a>倾向使用 `sprintf` 或其别名 `format` 而不是相当晦涩的 `String#%` 方法。<sup>[[link](#sprintf)]</sup>\n",
    "\n",
    "```ruby\n",
    "# 差\n",
    "'%d %d' % [20, 10]\n",
    "# => '20 10'\n",
    "\n",
    "# 好\n",
    "sprintf('%d %d', 20, 10)\n",
    "# => '20 10'\n",
    "\n",
    "# 好\n",
    "sprintf('%{first} %{second}', first: 20, second: 10)\n",
    "# => '20 10'\n",
    "\n",
    "format('%d %d', 20, 10)\n",
    "# => '20 10'\n",
    "\n",
    "# 好\n",
    "format('%{first} %{second}', first: 20, second: 10)\n",
    "# => '20 10'\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### <a name=\"array-join\"></a>倾向使用 `Array#join` 而不是相当晦涩的带字符参数的 `Array#*` 方法。<sup>[[link](#array-join)]</sup>\n",
    "\n",
    "```ruby\n",
    "# 差\n",
    "%w[one two three] * ', '\n",
    "# => 'one, two, three'\n",
    "\n",
    "# 好\n",
    "%w[one two three].join(', ')\n",
    "# => 'one, two, three'\n",
    "```\n",
    "\n",
    "#### <a name=\"array-coercion\"></a>当你希望处理的变量类型是数组，但不太确定其是否真的是数组时，通过使用 `Array()` 来替代显式的数组类型检查与转换。<sup>[[link](#array-coercion)]</sup>\n",
    "\n",
    "\n",
    "```ruby\n",
    "# 差\n",
    "paths = [paths] unless paths.is_a? Array\n",
    "paths.each { |path| do_something(path) }\n",
    "\n",
    "# 差 - 总是构建新的数组对象\n",
    "[*paths].each { |path| do_something(path) }\n",
    "\n",
    "# 好\n",
    "Array(paths).each { |path| do_something(path) }\n",
    "```\n",
    "\n",
    "#### <a name=\"ranges-or-between\"></a>通过使用范围或 `Comparable#between?` 来替代复杂的比较逻辑。<sup>[[link](#ranges-or-between)]</sup>\n",
    "\n",
    "```ruby\n",
    "# 差\n",
    "do_something if x >= 1000 && x <= 2000\n",
    "\n",
    "# 好\n",
    "do_something if (1000..2000).include?(x)\n",
    "\n",
    "# 好\n",
    "do_something if x.between?(1000, 2000)\n",
    "```\n",
    "\n",
    "#### <a name=\"predicate-methods\"></a>倾向使用谓词方法而不是 `==` 操作符。但数值比较除外。<sup>[[link](#predicate-methods)]</sup>\n",
    "\n",
    "```ruby\n",
    "# 差\n",
    "if x % 2 == 0\n",
    "end\n",
    "\n",
    "if x % 2 == 1\n",
    "end\n",
    "\n",
    "if x == nil\n",
    "end\n",
    "\n",
    "# 好\n",
    "if x.even?\n",
    "end\n",
    "\n",
    "if x.odd?\n",
    "end\n",
    "\n",
    "if x.nil?\n",
    "end\n",
    "\n",
    "if x.zero?\n",
    "end\n",
    "\n",
    "if x == 0\n",
    "end\n",
    "```\n",
    "\n",
    "#### <a name=\"no-non-nil-checks\"></a>不做显式的 `non-nil` 检查，除非检查对象是布尔变量。<sup>[[link](#no-non-nil-checks)]</sup>\n",
    "\n",
    "```ruby\n",
    "# 差\n",
    "do_something if !something.nil?\n",
    "do_something if something != nil\n",
    "\n",
    "# 好\n",
    "do_something if something\n",
    "\n",
    "# 好 - 检查对象是布尔变量\n",
    "def value_set?\n",
    "  !@some_boolean.nil?\n",
    "end\n",
    "```\n",
    "\n",
    "#### <a name=\"no-BEGIN-blocks\"></a>避免使用 `BEGIN` 区块。<sup>[[link](#no-BEGIN-blocks)]</sup>\n",
    "\n",
    "#### <a name=\"no-END-blocks\"></a>永远不要使用 `END` 区块。使用 `Kernel#at_exit` 来替代。<sup>[[link](#no-END-blocks)]</sup>\n",
    "\n",
    "```ruby\n",
    "# 差\n",
    "END { puts 'Goodbye!' }\n",
    "\n",
    "# 好\n",
    "at_exit { puts 'Goodbye!' }\n",
    "```\n",
    "\n",
    "#### <a name=\"no-flip-flops\"></a>避免使用 flip-flops 操作符。<sup>[[link](#no-flip-flops)]</sup>\n",
    "\n",
    "#### <a name=\"no-nested-conditionals\"></a>流程控制中，避免使用嵌套条件。<sup>[[link](#no-nested-conditionals)]</sup>\n",
    "\n",
    "倾向使用防御从句进行非法数据断言。防御从句是指处于方法顶部的条件语句，其能尽早地退出方法。\n",
    "\n",
    "```ruby\n",
    "# 差\n",
    "def compute_thing(thing)\n",
    "  if thing[:foo]\n",
    "    update_with_bar(thing[:foo])\n",
    "    if thing[:foo][:bar]\n",
    "      partial_compute(thing)\n",
    "    else\n",
    "      re_compute(thing)\n",
    "    end\n",
    "  end\n",
    "end\n",
    "\n",
    "# 好\n",
    "def compute_thing(thing)\n",
    "  return unless thing[:foo]\n",
    "  update_with_bar(thing[:foo])\n",
    "  return re_compute(thing) unless thing[:foo][:bar]\n",
    "  partial_compute(thing)\n",
    "end\n",
    "```\n",
    "\n",
    "循环中，倾向使用 `next` 而不是条件区块。\n",
    "\n",
    "```ruby\n",
    "# 差\n",
    "[0, 1, 2, 3].each do |item|\n",
    "  if item > 1\n",
    "    puts item\n",
    "  end\n",
    "end\n",
    "\n",
    "# 好\n",
    "[0, 1, 2, 3].each do |item|\n",
    "  next unless item > 1\n",
    "  puts item\n",
    "end\n",
    "```\n",
    "\n",
    "#### <a name=\"map-find-select-reduce-size\"></a>倾向使用 `map` 而不是 `collect`，`find` 而不是 `detect`，`select` 而不是 `find_all`，`reduce` 而不是 `inject` 以及 `size` 而不是 `length`。这不是一个硬性要求，如果使用别名可以增强可读性，使用它也没关系。这些别名方法继承自 Smalltalk 语言，但在别的语言并不通用。鼓励使用 `select` 而不是 `find_all` 的理由是前者与 `reject` 搭配起来一目了然。<sup>[[link](#map-find-select-reduce-size)]</sup>\n",
    "\n",
    "#### <a name=\"count-vs-size\"></a>不要使用 `count` 作为 `size` 的替代方案。除了 `Array` 外，其他 `Enumerable` 对象都需要通过枚举整个集合才可以确定数目。<sup>[[link](#count-vs-size)]</sup>\n",
    "\n",
    "```ruby\n",
    "# 差\n",
    "some_hash.count\n",
    "\n",
    "# 好\n",
    "some_hash.size\n",
    "```\n",
    "\n",
    "#### <a name=\"flat-map\"></a>倾向使用 `flat_map` 而不是 `map + flatten` 的组合。此规则并不适用于深度超过 2 层的数组。举例来说，如果 `users.first.songs == ['a', ['b','c']]` 成立，则使用 `map + flatten` 的组合而不是 `flat_map`。`flat_map` 只能平坦化一个层级，而 `flatten` 能够平坦化任意多个层级。<sup>[[link](#flat-map)]</sup>\n",
    "\n",
    "```ruby\n",
    "# 差\n",
    "all_songs = users.map(&:songs).flatten.uniq\n",
    "\n",
    "# 好\n",
    "all_songs = users.flat_map(&:songs).uniq\n",
    "```\n",
    "\n",
    "#### <a name=\"reverse-each\"></a>倾向使用 `reverse_each` 而不是 `reverse.each`，因为某些混入 `Enumerable` 模块的类可能会提供 `reverse_each` 的高效版本。即使这些类没有提供专门特化的版本，继承自 `Enumerable` 的通用版本至少能保证性能与 `reverse.each` 相当。<sup>[[link](#reverse-each)]</sup>\n",
    "\n",
    "```ruby\n",
    "# 差\n",
    "array.reverse.each { ... }\n",
    "\n",
    "# 好\n",
    "array.reverse_each { ... }\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## 命名\n",
    "\n",
    "> 程序设计的真正难题是替事物命名及使缓存失效。<br>\n",
    "> ——Phil Karlton"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### <a name=\"english-identifiers\"></a>标识符使用英文命名。<sup>[[link](#english-identifiers)]</sup>\n",
    "\n",
    "```ruby\n",
    "# 差 - 标识符使用非 ASCII 字符\n",
    "заплата = 1_000\n",
    "\n",
    "# 差 - 标识符使用拉丁文写法的保加利亚单词\n",
    "zaplata = 1_000\n",
    "\n",
    "# 好\n",
    "salary = 1_000\n",
    "```\n",
    "\n",
    "#### <a name=\"snake-case-symbols-methods-vars\"></a>符号、方法、变量使用蛇底式小写（`snake_case`）。<sup>[[link](#snake-case-symbols-methods-vars)]</sup>\n",
    "\n",
    "```ruby\n",
    "# 差\n",
    ":'some symbol'\n",
    ":SomeSymbol\n",
    ":someSymbol\n",
    "\n",
    "someVar = 5\n",
    "var_10 = 10\n",
    "\n",
    "def someMethod\n",
    "  ...\n",
    "end\n",
    "\n",
    "def SomeMethod\n",
    " ...\n",
    "end\n",
    "\n",
    "# 好\n",
    ":some_symbol\n",
    "\n",
    "some_var = 5\n",
    "var10 = 10\n",
    "\n",
    "def some_method\n",
    "  ...\n",
    "end\n",
    "```\n",
    "\n",
    "#### <a name=\"snake-case-symbols-methods-vars-with-numbers\"></a>给符号、方法、变量命名时，避免分隔字母与数字。<sup>[[link](#snake-case-symbols-methods-vars-with-numbers)]</sup>\n",
    "\n",
    "```ruby\n",
    "# 差\n",
    ":some_sym_1\n",
    "\n",
    "some_var_1 = 1\n",
    "\n",
    "def some_method_1\n",
    "  # 做一些事情\n",
    "end\n",
    "\n",
    "# 好\n",
    ":some_sym1\n",
    "\n",
    "some_var1 = 1\n",
    "\n",
    "def some_method1\n",
    "  # 做一些事情\n",
    "end\n",
    "```\n",
    "\n",
    "#### <a name=\"camelcase-classes\"></a>类与模块使用驼峰式大小写（`CamelCase`）。（HTTP、RFC、XML 等首字母缩写应该仍旧保持大写形式）<sup>[[link](#camelcase-classes)]</sup>\n",
    "\n",
    "```ruby\n",
    "# 差\n",
    "class Someclass\n",
    "  ...\n",
    "end\n",
    "\n",
    "class Some_Class\n",
    "  ...\n",
    "end\n",
    "\n",
    "class SomeXml\n",
    "  ...\n",
    "end\n",
    "\n",
    "class XmlSomething\n",
    "  ...\n",
    "end\n",
    "\n",
    "# 好\n",
    "class SomeClass\n",
    "  ...\n",
    "end\n",
    "\n",
    "class SomeXML\n",
    "  ...\n",
    "end\n",
    "\n",
    "class XMLSomething\n",
    "  ...\n",
    "end\n",
    "```\n",
    "\n",
    "#### <a name=\"snake-case-files\"></a>文件名使用蛇底式小写，如 `hello_world.rb`。<sup>[[link](#snake-case-files)]</sup>\n",
    "\n",
    "#### <a name=\"snake-case-dirs\"></a>目录名使用蛇底式小写，如 `lib/hello_world/hello_world.rb`。<sup>[[link](#snake-case-dirs)]</sup>\n",
    "\n",
    "#### <a name=\"one-class-per-file\"></a>尽量使一个源文件中只有一个类或模块。文件名就是类名或模块名，但使用蛇底式小写而不是驼峰式大小写。<sup>[[link](#one-class-per-file)]</sup>\n",
    "\n",
    "#### <a name=\"screaming-snake-case\"></a>其他常量使用尖叫蛇底式大写（SCREAMING_SNAKE_CASE）。<sup>[[link](#screaming-snake-case)]</sup>\n",
    "\n",
    "```ruby\n",
    "# 差\n",
    "SomeConst = 5\n",
    "\n",
    "# 好\n",
    "SOME_CONST = 5\n",
    "```\n",
    "\n",
    "#### <a name=\"bool-methods-qmark\"></a>谓词方法（返回布尔值的方法）的名字应当以问号结尾。（比如 `Array#empty?`）。不返回布尔值的方法不应以问号结尾。<sup>[[link](#bool-methods-qmark)]</sup>\n",
    "\n",
    "#### <a name=\"bool-methods-prefix\"></a>谓词方法的名字应当避免使用 `is`、`does`、`can` 等助动词作为前缀。这些助动词在实际场景中显得冗余，且与标准库的命名习惯（比如 `empty?`、`include?`）很不一致。<sup>[[link](#bool-methods-prefix)]</sup>\n",
    "\n",
    "```ruby\n",
    "# 差\n",
    "class Person\n",
    "  def is_tall?\n",
    "    true\n",
    "  end\n",
    "\n",
    "  def can_play_basketball?\n",
    "    false\n",
    "  end\n",
    "\n",
    "  def does_like_candy?\n",
    "    true\n",
    "  end\n",
    "end\n",
    "\n",
    "# 好\n",
    "class Person\n",
    "  def tall?\n",
    "    true\n",
    "  end\n",
    "\n",
    "  def basketball_player?\n",
    "    false\n",
    "  end\n",
    "\n",
    "  def likes_candy?\n",
    "    true\n",
    "  end\n",
    "end\n",
    "```\n",
    "\n",
    "#### <a name=\"dangerous-method-bang\"></a>\n",
    "具有潜在**危险性**的方法，当其存在对应安全版本的方法时，其名字应当以惊叹号结尾。<sup>[[link](#dangerous-method-bang)]</sup>\n",
    "\n",
    "（比如修改 `self` 或参数值的方法、相对 `exit` 方法不会在退出时运行 finalizers 执行清理工作的 `exit!` 方法等）\n",
    "\n",
    "```ruby\n",
    "# 差 - 没有对应安全版本的方法\n",
    "class Person\n",
    "  def update!\n",
    "  end\n",
    "end\n",
    "\n",
    "# 好\n",
    "class Person\n",
    "  def update\n",
    "  end\n",
    "end\n",
    "\n",
    "# 好\n",
    "class Person\n",
    "  def update!\n",
    "  end\n",
    "\n",
    "  def update\n",
    "  end\n",
    "end\n",
    "```\n",
    "\n",
    "## <a name=\"safe-because-unsafe\"></a>尽量根据危险方法来定义对应安全版本的方法。<sup>[[link](#safe-because-unsafe)]</sup>\n",
    "\n",
    "```ruby\n",
    "class Array\n",
    "  def flatten_once!\n",
    "    res = []\n",
    "\n",
    "    each do |e|\n",
    "      [*e].each { |f| res << f }\n",
    "    end\n",
    "\n",
    "    replace(res)\n",
    "  end\n",
    "\n",
    "  def flatten_once\n",
    "    dup.flatten_once!\n",
    "  end\n",
    "end\n",
    "```\n",
    "\n",
    "#### <a name=\"other-arg\"></a>当定义二元操作符时，将参数命名为 `other`（`<<` 与 `[]` 例外，因为其语义与此不同）。<sup>[[link](#other-arg)]</sup>\n",
    "\n",
    "```ruby\n",
    "def +(other)\n",
    "# 省略主体\n",
    "end\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## 注释\n",
    "\n",
    "> 良好的代码自身就是最佳的文档。当你要添加一个注释时，扪心自问，“如何改善代码让它不需要注释？” 改善代码，再写相应文档使之更清楚。<br>\n",
    "> ——Steve McConnell"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### <a name=\"no-comments\"></a>编写让人一目了然的代码然后忽略这一节的其它部分。我是认真的！<sup>[[link](#no-comments)]</sup>\n",
    "\n",
    "#### <a name=\"english-comments\"></a>使用英文编写注释。<sup>[[link](#english-comments)]</sup>\n",
    "\n",
    "#### <a name=\"hash-space\"></a>前导 `#` 与注释文本之间应当添加一个空格。<sup>[[link](#hash-space)]</sup>\n",
    "\n",
    "#### <a name=\"english-syntax\"></a>注释超过一个单词时，句首字母应当大写，并在语句停顿或结尾处使用标点符号。句号后添加[一个空格](http://en.wikipedia.org/wiki/Sentence_spacing)。<sup>[[link](#english-syntax)]</sup>\n",
    "\n",
    "#### <a name=\"no-superfluous-comments\"></a>避免无谓的注释。<sup>[[link](#no-superfluous-comments)]</sup>\n",
    "\n",
    "```ruby\n",
    "# 差\n",
    "counter += 1 # Increments counter by one.\n",
    "```\n",
    "\n",
    "#### <a name=\"comment-upkeep\"></a>及时更新注释。过时的注释比没有注释还要糟糕。<sup>[[link](#comment-upkeep)]</sup>\n",
    "\n",
    "> 好的代码就像是好的笑话 —— 它不需要解释。<br>\n",
    "> ——Russ Olsen\n",
    "\n",
    "#### <a name=\"refactor-dont-comment\"></a>避免替烂代码编写注释。重构它们使其变得一目了然。（要么做，要么不做，不要只是试试看。——Yoda）<sup>[[link](#refactor-dont-comment)]</sup>\n",
    "\n",
    "### 注解\n",
    "\n",
    "#### <a name=\"annotate-above\"></a>注解应该直接写在相关代码之前那行。<sup>[[link](#annotate-above)]</sup>\n",
    "\n",
    "#### <a name=\"annotate-keywords\"></a>注解关键字后面，跟着一个冒号及空格，接着是描述问题的文本。<sup>[[link](#annotate-keywords)]</sup>\n",
    "\n",
    "#### <a name=\"indent-annotations\"></a>如果需要用多行来描述问题，后续行要放在 `#` 后面并缩排两个空格。<sup>[[link](#indent-annotations)]</sup>\n",
    "\n",
    "```ruby\n",
    "def bar\n",
    "  # FIXME: This has crashed occasionally since v3.2.1. It may\n",
    "  #   be related to the BarBazUtil upgrade.\n",
    "  baz(:quux)\n",
    "end\n",
    "```\n",
    "\n",
    "#### <a name=\"rare-eol-annotations\"></a>当问题是显而易见时，任何文档都是多余的，注解应当放在有问题的那行末尾且不带任何多余说明。这个用法应该算是例外而不是规则。<sup>[[link](#rare-eol-annotations)]</sup>\n",
    "\n",
    "```ruby\n",
    "def bar\n",
    "  sleep 100 # OPTIMIZE\n",
    "end\n",
    "```\n",
    "\n",
    "#### <a name=\"todo\"></a>使用 `TODO` 标记应当加入的特征与功能。<sup>[[link](#todo)]</sup>\n",
    "\n",
    "#### <a name=\"fixme\"></a>使用 `FIXME` 标记需要修复的代码。<sup>[[link](#fixme)]</sup>\n",
    "\n",
    "#### <a name=\"optimize\"></a>使用 `OPTIMIZE` 标记可能引发性能问题的低效代码。<sup>[[link](#optimize)]</sup>\n",
    "\n",
    "#### <a name=\"hack\"></a>使用 `HACK` 标记代码异味，即那些应当被重构的可疑编码习惯。<sup>[[link](#hack)]</sup>\n",
    "\n",
    "#### <a name=\"review\"></a>使用 `REVIEW` 标记需要确认与编码意图是否一致的可疑代码。比如，`REVIEW: Are we sure this is how the client does X currently?`。<sup>[[link](#review)]</sup>\n",
    "\n",
    "#### <a name=\"document-annotations\"></a>适当情况下，可以自行定制其他注解关键字，但别忘记在项目的 `README` 或类似文档中予以说明。<sup>[[link](#document-annotations)]</sup>\n",
    "\n",
    "### Magic Comments\n",
    "\n",
    "#### <a name=\"magic-comments-first\"></a>Place magic comments above all code and documentation. Magic comments should only go below shebangs if they are needed in your source file.<sup>[[link](#magic-comments-first)]</sup>\n",
    "\n",
    "```ruby\n",
    "# good\n",
    "# frozen_string_literal: true\n",
    "# Some documentation about Person\n",
    "class Person\n",
    "end\n",
    "\n",
    "# bad\n",
    "# Some documentation about Person\n",
    "# frozen_string_literal: true\n",
    "class Person\n",
    "end\n",
    "```\n",
    "\n",
    "```ruby\n",
    "# good\n",
    "#!/usr/bin/env ruby\n",
    "# frozen_string_literal: true\n",
    "App.parse(ARGV)\n",
    "\n",
    "# bad\n",
    "# frozen_string_literal: true\n",
    "#!/usr/bin/env ruby\n",
    "App.parse(ARGV)\n",
    "```\n",
    "\n",
    "#### <a name=\"one-magic-comment-per-line\"></a>Use one magic comment per line if you need multiple.<sup>[[link](#one-magic-comment-per-line)]</sup>\n",
    "\n",
    "```ruby\n",
    "# good\n",
    "# frozen_string_literal: true\n",
    "# encoding: ascii-8bit\n",
    "\n",
    "# bad\n",
    "# -*- frozen_string_literal: true; encoding: ascii-8bit -*-\n",
    "```\n",
    "\n",
    "#### <a name=\"separate-magic-comments-from-code\"></a>Separate magic comments from code and documentation with a blank line.<sup>[[link](#separate-magic-comments-from-code)]</sup>\n",
    "\n",
    "```ruby\n",
    "# good\n",
    "# frozen_string_literal: true\n",
    "\n",
    "# Some documentation for Person\n",
    "class Person\n",
    "  # Some code\n",
    "end\n",
    "\n",
    "# bad\n",
    "# frozen_string_literal: true\n",
    "# Some documentation for Person\n",
    "class Person\n",
    "  # Some code\n",
    "end\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## 类与模块\n",
    "\n",
    "#### <a name=\"consistent-classes\"></a>在类定义中，使用一致的结构。<sup>[[link](#consistent-classes)]</sup>\n",
    "\n",
    "```ruby\n",
    "class Person\n",
    "  # 首先是 extend 与 include\n",
    "  extend SomeModule\n",
    "  include AnotherModule\n",
    "\n",
    "  # 内部类\n",
    "  CustomError = Class.new(StandardError)\n",
    "\n",
    "  # 接着是常量\n",
    "  SOME_CONSTANT = 20\n",
    "\n",
    "  # 接下来是属性宏\n",
    "  attr_reader :name\n",
    "\n",
    "  # 跟着是其他宏（如果有的话）\n",
    "  validates :name\n",
    "\n",
    "  # 公开的类方法接在下一行\n",
    "  def self.some_method\n",
    "  end\n",
    "\n",
    "  # 初始化方法在类方法和实例方法之间\n",
    "  def initialize\n",
    "  end\n",
    "\n",
    "  # 跟着是公开的实例方法\n",
    "  def some_method\n",
    "  end\n",
    "\n",
    "  # 受保护及私有的方法等放在接近结尾的地方\n",
    "  protected\n",
    "\n",
    "  def some_protected_method\n",
    "  end\n",
    "\n",
    "  private\n",
    "\n",
    "  def some_private_method\n",
    "  end\n",
    "end\n",
    "```\n",
    "\n",
    "#### <a name=\"mixin-grouping\"></a>在混入多个模块时，倾向使用多行语法。<sup>[[link](#mixin-grouping)]</sup>\n",
    "\n",
    "```ruby\n",
    "# 差\n",
    "class Person\n",
    "  include Foo, Bar\n",
    "end\n",
    "\n",
    "# 好\n",
    "class Person\n",
    "  include Foo\n",
    "  include Bar\n",
    "end\n",
    "```\n",
    "\n",
    "#### <a name=\"file-classes\"></a>如果嵌套类数目较多，进而导致外围类定义较长，则将它们从外围类中提取出来，分别放置在单独的以嵌套类命名的文件中，并将文件归类至以外围类命名的文件夹下。<sup>[[link](#file-classes)]</sup>\n",
    "\n",
    "```Ruby\n",
    "# 差\n",
    "\n",
    "# foo.rb\n",
    "class Foo\n",
    "  class Bar\n",
    "    # 定义 30 多个方法\n",
    "  end\n",
    "\n",
    "  class Car\n",
    "    # 定义 20 多个方法\n",
    "  end\n",
    "\n",
    "  # 定义 30 多个方法\n",
    "end\n",
    "\n",
    "# 好\n",
    "\n",
    "# foo.rb\n",
    "class Foo\n",
    "  # 定义 30 多个方法\n",
    "end\n",
    "\n",
    "# foo/bar.rb\n",
    "class Foo\n",
    "  class Bar\n",
    "    # 定义 30 多个方法\n",
    "  end\n",
    "end\n",
    "\n",
    "# foo/car.rb\n",
    "class Foo\n",
    "  class Car\n",
    "    # 定义 20 多个方法\n",
    "  end\n",
    "end\n",
    "```\n",
    "\n",
    "#### <a name=\"modules-vs-classes\"></a>定义只有类方法的数据类型时，倾向使用模块而不是类。只有当需要实例化时才使用类。<sup>[[link](#modules-vs-classes)]</sup>\n",
    "\n",
    "```ruby\n",
    "# 差\n",
    "class SomeClass\n",
    "  def self.some_method\n",
    "    # 省略主体\n",
    "  end\n",
    "\n",
    "  def self.some_other_method\n",
    "    # 省略主体\n",
    "  end\n",
    "end\n",
    "\n",
    "# 好\n",
    "module SomeModule\n",
    "  module_function\n",
    "\n",
    "  def some_method\n",
    "    # 省略主体\n",
    "  end\n",
    "\n",
    "  def some_other_method\n",
    "    # 省略主体\n",
    "  end\n",
    "end\n",
    "```\n",
    "\n",
    "#### <a name=\"module-function\"></a>当你想将模块的实例方法变成类方法时，倾向使用 `module_function` 而不是 `extend self`。<sup>[[link](#module-function)]</sup>\n",
    "\n",
    "```ruby\n",
    "# 差\n",
    "module Utilities\n",
    "  extend self\n",
    "\n",
    "  def parse_something(string)\n",
    "    # 做一些事情\n",
    "  end\n",
    "\n",
    "  def other_utility_method(number, string)\n",
    "    # 做一些事情\n",
    "  end\n",
    "end\n",
    "\n",
    "# 好\n",
    "module Utilities\n",
    "  module_function\n",
    "\n",
    "  def parse_something(string)\n",
    "    # 做一些事情\n",
    "  end\n",
    "\n",
    "  def other_utility_method(number, string)\n",
    "    # 做一些事情\n",
    "  end\n",
    "end\n",
    "```\n",
    "\n",
    "#### <a name=\"liskov\"></a>当设计类的层次结构时，确保它们符合[里式替换原则](http://en.wikipedia.org/wiki/Liskov_substitution_principle)。<sup>[[link](#liskov)]</sup>\n",
    "\n",
    "#### <a name=\"solid-design\"></a>让你的类尽量满足 [SOLID 原则](http://en.wikipedia.org/wiki/SOLID_(object-oriented_design)) 。<sup>[[link](#solid-design)]</sup>\n",
    "\n",
    "#### <a name=\"define-to-s\"></a>总是替那些用以表示领域模型的类提供一个适当的 `to_s` 方法。<sup>[[link](#define-to-s)]</sup>\n",
    "\n",
    "```ruby\n",
    "class Person\n",
    "  attr_reader :first_name, :last_name\n",
    "\n",
    "  def initialize(first_name, last_name)\n",
    "    @first_name = first_name\n",
    "    @last_name = last_name\n",
    "  end\n",
    "\n",
    "  def to_s\n",
    "    \"#{@first_name} #{@last_name}\"\n",
    "  end\n",
    "end\n",
    "```\n",
    "\n",
    "#### <a name=\"attr_family\"></a>使用 `attr` 系列方法来定义琐碎的存取器或修改器。<sup>[[link](#attr_family)]</sup>\n",
    "\n",
    "```ruby\n",
    "# 差\n",
    "class Person\n",
    "  def initialize(first_name, last_name)\n",
    "    @first_name = first_name\n",
    "    @last_name = last_name\n",
    "  end\n",
    "\n",
    "  def first_name\n",
    "    @first_name\n",
    "  end\n",
    "\n",
    "  def last_name\n",
    "    @last_name\n",
    "  end\n",
    "end\n",
    "\n",
    "# 好\n",
    "class Person\n",
    "  attr_reader :first_name, :last_name\n",
    "\n",
    "  def initialize(first_name, last_name)\n",
    "    @first_name = first_name\n",
    "    @last_name = last_name\n",
    "  end\n",
    "end\n",
    "```\n",
    "\n",
    "#### <a name=\"accessor_mutator_method_names\"></a>对于访问器方法，避免使用 `get_` 作为名字前缀；对于更改器方法，避免使用 `set_` 作为名字前缀。Ruby 语言中，通常使用 `attr_name` 作为访问器的方法名，使用 `attr_name=` 作为更改器的方法名。<sup>[[link](#accessor_mutator_method_names)]</sup>\n",
    "\n",
    "```ruby\n",
    "# 差\n",
    "class Person\n",
    "  def get_name\n",
    "    \"#{@first_name} #{@last_name}\"\n",
    "  end\n",
    "\n",
    "  def set_name(name)\n",
    "    @first_name, @last_name = name.split(' ')\n",
    "  end\n",
    "end\n",
    "\n",
    "# 好\n",
    "class Person\n",
    "  def name\n",
    "    \"#{@first_name} #{@last_name}\"\n",
    "  end\n",
    "\n",
    "  def name=(name)\n",
    "    @first_name, @last_name = name.split(' ')\n",
    "  end\n",
    "end\n",
    "```\n",
    "\n",
    "#### <a name=\"attr\"></a>避免使用 `attr`。使用 `attr_reader` 与 `attr_accessor` 来替代。<sup>[[link](#attr)]</sup>\n",
    "\n",
    "```ruby\n",
    "# 差 - 创建单个存取方法（此方法在 Ruby 1.9 之后被移除了）\n",
    "attr :something, true\n",
    "attr :one, :two, :three # 类似于 attr_reader\n",
    "\n",
    "# 好\n",
    "attr_accessor :something\n",
    "attr_reader :one, :two, :three\n",
    "```\n",
    "\n",
    "#### <a name=\"struct-new\"></a>优先考虑使用 `Struct.new`。它替你定义了那些琐碎的访问器、构造器及比较操作符。<sup>[[link](#struct-new)]</sup>\n",
    "\n",
    "```ruby\n",
    "# 好\n",
    "class Person\n",
    "  attr_accessor :first_name, :last_name\n",
    "\n",
    "  def initialize(first_name, last_name)\n",
    "    @first_name = first_name\n",
    "    @last_name = last_name\n",
    "  end\n",
    "end\n",
    "\n",
    "# 更好\n",
    "Person = Struct.new(:first_name, :last_name) do\n",
    "end\n",
    "```\n",
    "\n",
    "#### <a name=\"no-extend-struct-new\"></a>不要扩展 `Struct.new` 实例化后的对象。对它进行扩展不但引入了毫无意义的类层次，而且在此文件被多次引入时可能会产生奇怪的错误。<sup>[[link](#no-extend-struct-new)]</sup>\n",
    "\n",
    "```ruby\n",
    "# 差\n",
    "class Person < Struct.new(:first_name, :last_name)\n",
    "end\n",
    "\n",
    "# 好\n",
    "Person = Struct.new(:first_name, :last_name)\n",
    "```\n",
    "\n",
    "#### <a name=\"factory-methods\"></a>优先考虑通过工厂方法的方式创建某些具有特定意义的实例对象。<sup>[[link](#factory-methods)]</sup>\n",
    "\n",
    "```ruby\n",
    "class Person\n",
    "  def self.create(options_hash)\n",
    "    # 省略主体\n",
    "  end\n",
    "end\n",
    "```\n",
    "\n",
    "#### <a name=\"duck-typing\"></a>倾向使用[鸭子类型](https://en.wikipedia.org/wiki/Duck_typing)而不是继承。<sup>[[link](#duck-typing)]</sup>\n",
    "\n",
    "```ruby\n",
    "# 差\n",
    "class Animal\n",
    "  # 抽象方法\n",
    "  def speak\n",
    "  end\n",
    "end\n",
    "\n",
    "# 继承父类\n",
    "class Duck < Animal\n",
    "  def speak\n",
    "    puts 'Quack! Quack'\n",
    "  end\n",
    "end\n",
    "\n",
    "# 继承父类\n",
    "class Dog < Animal\n",
    "  def speak\n",
    "    puts 'Bau! Bau!'\n",
    "  end\n",
    "end\n",
    "\n",
    "# 好\n",
    "class Duck\n",
    "  def speak\n",
    "    puts 'Quack! Quack'\n",
    "  end\n",
    "end\n",
    "\n",
    "class Dog\n",
    "  def speak\n",
    "    puts 'Bau! Bau!'\n",
    "  end\n",
    "end\n",
    "```\n",
    "\n",
    "#### <a name=\"no-class-vars\"></a>避免使用类变量（`@@`）。类变量在继承方面存在令人生厌的行为。<sup>[[link](#no-class-vars)]</sup>\n",
    "\n",
    "```ruby\n",
    "class Parent\n",
    "  @@class_var = 'parent'\n",
    "\n",
    "  def self.print_class_var\n",
    "    puts @@class_var\n",
    "  end\n",
    "end\n",
    "\n",
    "class Child < Parent\n",
    "  @@class_var = 'child'\n",
    "end\n",
    "\n",
    "Parent.print_class_var # => 此处打印的结果为 'child'\n",
    "```\n",
    "\n",
    "如你所见，在类的层次结构中所有类都会共享同一类变量。通常情况下，倾向使用类实例变量而不是类变量。\n",
    "\n",
    "#### <a name=\"visibility\"></a>根据方法的目的与用途设置适当的可见级别（`private`、`protected`）。不要什么都不做就把所有方法设置为 `public`（默认值）。毕竟我们写的是 **Ruby** 而不是 **Python**。<sup>[[link](#visibility)]</sup>\n",
    "\n",
    "#### <a name=\"indent-public-private-protected\"></a>把 `public`、`protected`、`private` 与其作用的方法缩排在同一层级。且在其上下各留一行以强调此可见级别作用于之后的所有方法。<sup>[[link](#indent-public-private-protected)]</sup>\n",
    "\n",
    "```ruby\n",
    "class SomeClass\n",
    "  def public_method\n",
    "    # ...\n",
    "  end\n",
    "\n",
    "  private\n",
    "\n",
    "  def private_method\n",
    "    # ...\n",
    "  end\n",
    "\n",
    "  def another_private_method\n",
    "    # ...\n",
    "  end\n",
    "end\n",
    "```\n",
    "\n",
    "#### <a name=\"def-self-class-methods\"></a>使用 `def self.method` 定义类方法。这种做法使得在代码重构时，即使修改了类名也无需做多次修改。<sup>[[link](#def-self-class-methods)]</sup>\n",
    "\n",
    "```ruby\n",
    "class TestClass\n",
    "  # 差\n",
    "  def TestClass.some_method\n",
    "    # 省略主体\n",
    "  end\n",
    "\n",
    "  # 好\n",
    "  def self.some_other_method\n",
    "    # 省略主体\n",
    "  end\n",
    "\n",
    "  # 在需要定义多个类方法时，另一种便捷写法\n",
    "  class << self\n",
    "    def first_method\n",
    "      # 省略主体\n",
    "    end\n",
    "\n",
    "    def second_method_etc\n",
    "      # 省略主体\n",
    "    end\n",
    "  end\n",
    "end\n",
    "```\n",
    "\n",
    "#### <a name=\"alias-method-lexically\"></a>在类的词法作用域中定义方法别名时，倾向使用 `alias`。因为定义期间 `alias` 与 `self` 指向的都是词法作用域，除非明确说明，否则该别名所引用的方法不会在运行期间被改变，或是在任何子类中被修改。<sup>[[link](#alias-method-lexically)]</sup>\n",
    "\n",
    "```ruby\n",
    "class Westerner\n",
    "  def first_name\n",
    "    @names.first\n",
    "  end\n",
    "\n",
    "  alias given_name first_name\n",
    "end\n",
    "```\n",
    "\n",
    "因为 `alias` 与 `def` 一样都是关键字，倾向使用裸字而不是符号或字符串。也就是说，使用 `alias foo bar` 而不是 `alias :foo :bar`。\n",
    "\n",
    "另外需要了解 Ruby 是如何处理别名和继承的：别名所引用的原始方法是在定义期间被指定的，而不是运行期间。\n",
    "\n",
    "```ruby\n",
    "class Fugitive < Westerner\n",
    "  def first_name\n",
    "    'Nobody'\n",
    "  end\n",
    "end\n",
    "```\n",
    "\n",
    "在这个例子中，`Fugitive#given_name` 仍然调用原先的 `Westerner#first_name` 方法，而不是 `Fugitive#first_name`。如果想要覆写 `Fugitive#given_name`，必须在子类中重新定义。\n",
    "\n",
    "```ruby\n",
    "class Fugitive < Westerner\n",
    "  def first_name\n",
    "    'Nobody'\n",
    "  end\n",
    "\n",
    "  alias given_name first_name\n",
    "end\n",
    "```\n",
    "\n",
    "#### <a name=\"alias-method\"></a>在运行期间定义模块方法、类方法、单件方法的别名时，总是使用 `alias_method`。在上述情况下，使用 `alias` 可能会导致预期之外的结果。<sup>[[link](#alias-method)]</sup>\n",
    "\n",
    "```ruby\n",
    "module Mononymous\n",
    "  def self.included(other)\n",
    "    other.class_eval { alias_method :full_name, :given_name }\n",
    "  end\n",
    "end\n",
    "\n",
    "class Sting < Westerner\n",
    "  include Mononymous\n",
    "end\n",
    "```\n",
    "\n",
    "#### <a name=\"class-and-self\"></a>在模块方法，或是类方法内部调用自身其他方法时，通常省略模块名/类名/`self`。<sup>[[link](#class-and-self)]</sup>\n",
    "\n",
    "```ruby\n",
    "class TestClass\n",
    "  # 差\n",
    "  def self.call(param1, param2)\n",
    "    TestClass.new(param1).call(param2)\n",
    "  end\n",
    "\n",
    "  # 差\n",
    "  def self.call(param1, param2)\n",
    "    self.new(param1).call(param2)\n",
    "  end\n",
    "\n",
    "  # 好\n",
    "  def self.call(param1, param2)\n",
    "    new(param1).call(param2)\n",
    "  end\n",
    "\n",
    "  # 省略其他方法\n",
    "end\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## 异常\n",
    "\n",
    "#### <a name=\"prefer-raise-over-fail\"></a>对于异常处理，倾向使用 `raise` 而不是 `fail`。<sup>[[link](#prefer-raise-over-fail)]</sup>\n",
    "\n",
    "```ruby\n",
    "# 差\n",
    "fail SomeException, 'message'\n",
    "\n",
    "# 好\n",
    "raise SomeException, 'message'\n",
    "```\n",
    "\n",
    "#### <a name=\"no-explicit-runtimeerror\"></a>不要在带双参数形式的 `raise` 方法中显式指定 `RuntimeError`。<sup>[[link](#no-explicit-runtimeerror)]</sup>\n",
    "\n",
    "```ruby\n",
    "# 差\n",
    "raise RuntimeError, 'message'\n",
    "\n",
    "# 好 - 默认就是 RuntimeError\n",
    "raise 'message'\n",
    "```\n",
    "\n",
    "#### <a name=\"exception-class-messages\"></a>倾向使用带异常类、消息的双参数形式调用 `raise` 方法，而不是使用异常的实例。<sup>[[link](#exception-class-messages)]</sup>\n",
    "\n",
    "```ruby\n",
    "# 差 - 并无 raise SomeException.new('message') [, backtraces] 这种调用形式\n",
    "raise SomeException.new('message')\n",
    "\n",
    "# 好 - 与调用形式 raise SomeException [, 'message' [, backtraces]] 保持一致\n",
    "raise SomeException, 'message'\n",
    "```\n",
    "\n",
    "#### <a name=\"no-return-ensure\"></a>永远不要从 `ensure` 区块返回。如果你显式地从 `ensure` 区块返回，那么其所在的方法会如同永远不会发生异常般的返回。事实上，异常被默默地丢弃了。<sup>[[link](#no-return-ensure)]</sup>\n",
    "\n",
    "```ruby\n",
    "def foo\n",
    "  raise\n",
    "ensure\n",
    "  return 'very bad idea'\n",
    "end\n",
    "```\n",
    "\n",
    "#### <a name=\"begin-implicit\"></a>尽可能隐式地使用 `begin/rescue/ensure/end` 区块。<sup>[[link](#begin-implicit)]</sup>\n",
    "\n",
    "```ruby\n",
    "# 差\n",
    "def foo\n",
    "  begin\n",
    "    # 主逻辑\n",
    "  rescue\n",
    "    # 异常处理逻辑\n",
    "  end\n",
    "end\n",
    "\n",
    "# 好\n",
    "def foo\n",
    "  # 主逻辑\n",
    "rescue\n",
    "  # 异常处理逻辑\n",
    "end\n",
    "```\n",
    "\n",
    "#### <a name=\"contingency-methods\"></a>通过使用 **contingency 方法**（一个由 Avdi Grimm 创造的词）来减少 `begin/rescue/ensure/end` 区块的使用。<sup>[[link](#contingency-methods)]</sup>\n",
    "\n",
    "```ruby\n",
    "# 差\n",
    "begin\n",
    "  something_that_might_fail\n",
    "rescue IOError\n",
    "  # 处理 IOError\n",
    "end\n",
    "\n",
    "begin\n",
    "  something_else_that_might_fail\n",
    "rescue IOError\n",
    "  # 处理 IOError\n",
    "end\n",
    "\n",
    "# 好\n",
    "def with_io_error_handling\n",
    "   yield\n",
    "rescue IOError\n",
    "  # 处理 IOError\n",
    "end\n",
    "\n",
    "with_io_error_handling { something_that_might_fail }\n",
    "\n",
    "with_io_error_handling { something_else_that_might_fail }\n",
    "```\n",
    "\n",
    "#### <a name=\"dont-hide-exceptions\"></a>不要抑制异常。<sup>[[link](#dont-hide-exceptions)]</sup>\n",
    "\n",
    "```ruby\n",
    "# 差\n",
    "begin\n",
    "  # 抛出异常\n",
    "rescue SomeError\n",
    "  # 不做任何相关处理\n",
    "end\n",
    "\n",
    "# 差\n",
    "do_something rescue nil\n",
    "```\n",
    "\n",
    "#### <a name=\"no-rescue-modifiers\"></a>避免使用 `rescue` 修饰语法。<sup>[[link](#no-rescue-modifiers)]</sup>\n",
    "\n",
    "```ruby\n",
    "# 差 - 这里将会捕捉 StandardError 及其所有子孙类的异常\n",
    "read_file rescue handle_error($!)\n",
    "\n",
    "# 好 - 这里只会捕获 Errno::ENOENT 及其所有子孙类的异常\n",
    "def foo\n",
    "  read_file\n",
    "rescue Errno::ENOENT => ex\n",
    "  handle_error(ex)\n",
    "end\n",
    "```\n",
    "\n",
    "#### <a name=\"no-exceptional-flows\"></a>不要将异常处理作为流程控制使用。<sup>[[link](#no-exceptional-flows)]</sup>\n",
    "\n",
    "```ruby\n",
    "# 差\n",
    "begin\n",
    "  n / d\n",
    "rescue ZeroDivisionError\n",
    "  puts 'Cannot divide by 0!'\n",
    "end\n",
    "\n",
    "# 好\n",
    "if d.zero?\n",
    "  puts 'Cannot divide by 0!'\n",
    "else\n",
    "  n / d\n",
    "end\n",
    "```\n",
    "\n",
    "#### <a name=\"no-blind-rescues\"></a>避免捕获 `Exception`。这种做法会同时将信号与 `exit` 方法困住，导致你必须使用 `kill -9` 来终止进程。<sup>[[link](#no-blind-rescues)]</sup>\n",
    "\n",
    "```ruby\n",
    "# 差 - 信号与 exit 方法产生的异常会被捕获（除了 kill -9）\n",
    "begin\n",
    "  exit\n",
    "rescue Exception\n",
    "  puts \"you didn't really want to exit, right?\"\n",
    "  # 处理异常\n",
    "end\n",
    "\n",
    "# 好 - 没有指定具体异常的 rescue 子句默认捕获 StandardError\n",
    "begin\n",
    "  # 抛出异常\n",
    "rescue => e\n",
    "  # 处理异常\n",
    "end\n",
    "\n",
    "# 好 - 指定具体异常 StandardError\n",
    "begin\n",
    "  # 抛出异常\n",
    "rescue StandardError => e\n",
    "  # 处理异常\n",
    "end\n",
    "```\n",
    "\n",
    "#### <a name=\"exception-ordering\"></a>把较具体的异常放在处理链的较上层，不然它们永远不会被执行。<sup>[[link](#exception-ordering)]</sup>\n",
    "\n",
    "```ruby\n",
    "# 差\n",
    "begin\n",
    "  # 抛出异常\n",
    "rescue StandardError => e\n",
    "  # 处理异常\n",
    "rescue IOError => e\n",
    "  # 处理异常，但事实上永远不会被执行\n",
    "end\n",
    "\n",
    "# 好\n",
    "begin\n",
    "  # 抛出异常\n",
    "rescue IOError => e\n",
    "  # 处理异常\n",
    "rescue StandardError => e\n",
    "  # 处理异常\n",
    "end\n",
    "```\n",
    "\n",
    "#### <a name=\"release-resources\"></a>在 `ensure` 区块释放程序的外部资源。<sup>[[link](#release-resources)]</sup>\n",
    "\n",
    "```ruby\n",
    "f = File.open('testfile')\n",
    "begin\n",
    "  # .. 文件操作\n",
    "rescue\n",
    "  # .. 处理异常\n",
    "ensure\n",
    "  f.close if f\n",
    "end\n",
    "  ```\n",
    "\n",
    "#### <a name=\"auto-release-resources\"></a>在调用资源获取方法时，尽量使用具备自动清理功能的版本。<sup>[[link](#auto-release-resources)]</sup>\n",
    "\n",
    "```ruby\n",
    "# 差 - 需要显式关闭文件描述符\n",
    "f = File.open('testfile')\n",
    "  # ...\n",
    "f.close\n",
    "\n",
    "# 好 - 文件描述符会被自动关闭\n",
    "File.open('testfile') do |f|\n",
    "  # ...\n",
    "end\n",
    "  ```\n",
    "\n",
    "####  <a name=\"standard-exceptions\"></a>倾向使用标准库中的异常类而不是引入新的类型。<sup>[[link](#standard-exceptions)]</sup>"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## 集合\n",
    "\n",
    "#### <a name=\"literal-array-hash\"></a>对于数组与哈希，倾向使用字面量语法来构建实例（除非你需要给构造器传递参数）。<sup>[[link](#literal-array-hash)]</sup>\n",
    "\n",
    "```ruby\n",
    "# 差\n",
    "arr = Array.new\n",
    "hash = Hash.new\n",
    "\n",
    "# 好\n",
    "arr = []\n",
    "hash = {}\n",
    "```\n",
    "\n",
    "#### <a name=\"percent-w\"></a>当创建一组元素为单词（没有空格或特殊字符）的数组时，倾向使用 `%w` 而不是 `[]`。此规则只适用于数组元素有两个或以上的时候。<sup>[[link](#percent-w)]</sup>\n",
    "\n",
    "```ruby\n",
    "# 差\n",
    "STATES = ['draft', 'open', 'closed']\n",
    "\n",
    "# 好\n",
    "STATES = %w[draft open closed]\n",
    "```\n",
    "\n",
    "#### <a name=\"percent-i\"></a>当创建一组符号类型的数组（且不需要保持 Ruby 1.9 兼容性）时，倾向使用 `%i`。此规则只适用于数组元素有两个或以上的时候。<sup>[[link](#percent-i)]</sup>\n",
    "\n",
    "```ruby\n",
    "# 差\n",
    "STATES = [:draft, :open, :closed]\n",
    "\n",
    "# 好\n",
    "STATES = %i[draft open closed]\n",
    "```\n",
    "\n",
    "#### <a name=\"no-trailing-array-commas\"></a>避免在数组与哈希的字面量语法的最后一个元素之后添加逗号，尤其当元素没有分布在同一行时。<sup>[[link](#no-trailing-array-commas)]</sup>\n",
    "\n",
    "```ruby\n",
    "# 差 - 尽管移动、新增、删除元素颇为方便，但仍不推荐这种写法\n",
    "VALUES = [\n",
    "           1001,\n",
    "           2020,\n",
    "           3333,\n",
    "         ]\n",
    "\n",
    "# 差\n",
    "VALUES = [1001, 2020, 3333, ]\n",
    "\n",
    "# 好\n",
    "VALUES = [1001, 2020, 3333]\n",
    "```\n",
    "\n",
    "#### <a name=\"no-gappy-arrays\"></a>避免在数组中创造巨大的间隔。<sup>[[link](#no-gappy-arrays)]</sup>\n",
    "\n",
    "```ruby\n",
    "arr = []\n",
    "arr[100] = 1 # 现在你有一个很多 nil 的数组\n",
    "```\n",
    "\n",
    "#### <a name=\"first-and-last\"></a>当访问数组的首元素或尾元素时，倾向使用 `first` 或 `last` 而不是 `[0]` 或 `[-1]`。<sup>[[link](#first-and-last)]</sup>\n",
    "\n",
    "#### <a name=\"set-vs-array\"></a>当处理的对象不存在重复元素时，使用 `Set` 来替代 `Array`。`Set` 是实现了无序且无重复元素的集合类型。它兼具 `Array` 的直观操作与 `Hash` 的快速查找。<sup>[[link](#set-vs-array)]</sup>\n",
    "\n",
    "#### <a name=\"symbols-as-keys\"></a>倾向使用符号而不是字符串作为哈希键。<sup>[[link](#symbols-as-keys)]</sup>\n",
    "\n",
    "```ruby\n",
    "# 差\n",
    "hash = { 'one' => 1, 'two' => 2, 'three' => 3 }\n",
    "\n",
    "# 好\n",
    "hash = { one: 1, two: 2, three: 3 }\n",
    "```\n",
    "\n",
    "#### <a name=\"no-mutable-keys\"></a>避免使用可变对象作为哈希键。<sup>[[link](#no-mutable-keys)]</sup>\n",
    "\n",
    "#### <a name=\"hash-literals\"></a>当哈希键为符号时，使用 Ruby 1.9 的字面量语法。\n",
    "<sup>[[link](#hash-literals)]</sup>\n",
    "\n",
    "```ruby\n",
    "# 差\n",
    "hash = { :one => 1, :two => 2, :three => 3 }\n",
    "\n",
    "# 好\n",
    "hash = { one: 1, two: 2, three: 3 }\n",
    "```\n",
    "\n",
    "#### <a name=\"no-mixed-hash-syntaces\"></a>当哈希键既有符号又有字符串时，不要使用 Ruby 1.9 的字面量语法。<sup>[[link](#no-mixed-hash-syntaces)]</sup>\n",
    "\n",
    "  ```Ruby\n",
    "  # 差\n",
    "  { a: 1, 'b' => 2 }\n",
    "\n",
    "  # 好\n",
    "  { :a => 1, 'b' => 2 }\n",
    "  ```\n",
    "\n",
    "#### <a name=\"hash-key\"></a>倾向使用 `Hash#key?` 而不是 `Hash#has_key?`，使用 `Hash#value?` 而不是 `Hash#has_value?`。\n",
    "<sup>[[link](#hash-key)]</sup>\n",
    "\n",
    "```ruby\n",
    "# 差\n",
    "hash.has_key?(:test)\n",
    "hash.has_value?(value)\n",
    "\n",
    "# 好\n",
    "hash.key?(:test)\n",
    "hash.value?(value)\n",
    "```\n",
    "#### <a name=\"hash-each\"></a>倾向使用 `Hash#each_key` 而不是 `Hash#keys.each`，使用 `Hash#each_value` 而不是 `Hash#values.each`。<sup>[[link](#hash-each)]</sup>\n",
    "\n",
    "```ruby\n",
    "# 差\n",
    "hash.keys.each { |k| p k }\n",
    "hash.values.each { |v| p v }\n",
    "hash.each { |k, _v| p k }\n",
    "hash.each { |_k, v| p v }\n",
    "\n",
    "# 好\n",
    "hash.each_key { |k| p k }\n",
    "hash.each_value { |v| p v }\n",
    "```\n",
    "\n",
    "#### <a name=\"hash-fetch\"></a>当处理应该存在的哈希键时，使用 `Hash#fetch`。<sup>[[link](#hash-fetch)]</sup>\n",
    "\n",
    "```ruby\n",
    "heroes = { batman: 'Bruce Wayne', superman: 'Clark Kent' }\n",
    "\n",
    "# 差 - 如果我们打错了哈希键，则难以发现这个错误\n",
    "heroes[:batman] # => 'Bruce Wayne'\n",
    "heroes[:supermann] # => nil\n",
    "\n",
    "# 好 - fetch 会抛出 KeyError 使这个错误显而易见\n",
    "heroes.fetch(:supermann)\n",
    "```\n",
    "\n",
    "#### <a name=\"hash-fetch-defaults\"></a>当为哈希键的值提供默认值时，倾向使用 `Hash#fetch` 而不是自定义逻辑。<sup>[[link](#hash-fetch-defaults)]</sup>\n",
    "\n",
    "```ruby\n",
    "batman = { name: 'Bruce Wayne', is_evil: false }\n",
    "\n",
    "# 差 - 如果仅仅使用 || 操作符，那么当值为假时，我们不会得到预期结果\n",
    "batman[:is_evil] || true # => true\n",
    "\n",
    "# 好 - fetch 在遇到假值时依然可以正确工作\n",
    "batman.fetch(:is_evil, true) # => false\n",
    "```\n",
    "\n",
    "#### <a name=\"use-hash-blocks\"></a>当提供默认值的求值代码具有副作用或开销较大时，倾向使用 `Hash#fetch` 的区块形式。<sup>[[link](#use-hash-blocks)]</sup>\n",
    "\n",
    "```ruby\n",
    "batman = { name: 'Bruce Wayne' }\n",
    "\n",
    "# 差 - 此形式会立即求值，如果调用多次，可能会影响程序的性能\n",
    "batman.fetch(:powers, obtain_batman_powers) # obtain_batman_powers 开销较大\n",
    "\n",
    "# 好 - 此形式会惰性求值，只有抛出 KeyError 时，才会产生开销\n",
    "batman.fetch(:powers) { obtain_batman_powers }\n",
    "```\n",
    "\n",
    "### <a name=\"hash-values-at\"></a>当需要一次性从哈希中获取多个键的值时，使用 `Hash#values_at`。<sup>[[link](#hash-values-at)]</sup>\n",
    "\n",
    " ```ruby\n",
    " # 差\n",
    " email = data['email']\n",
    " username = data['nickname']\n",
    "\n",
    " # 好\n",
    " email, username = data.values_at('email', 'nickname')\n",
    " ```\n",
    "\n",
    "#### <a name=\"ordered-hashes\"></a>利用“Ruby 1.9 之后的哈希是有序的”的这个特性。<sup>[[link](#ordered-hashes)]</sup>\n",
    "\n",
    "#### <a name=\"no-modifying-collections\"></a>当遍历集合时，不要改动它。<sup>[[link](#no-modifying-collections)]</sup>\n",
    "\n",
    "#### <a name=\"accessing-elements-directly\"></a>当访问集合中的元素时，倾向使用对象所提供的方法进行访问，而不是直接调用对象属性上的 `[n]` 方法。这种做法可以防止你在 `nil` 对象上调用 `[]`。<sup>[[link](#accessing-elements-directly)]</sup>\n",
    "\n",
    "```ruby\n",
    "# 差\n",
    "Regexp.last_match[1]\n",
    "\n",
    "# 好\n",
    "Regexp.last_match(1)\n",
    "```\n",
    "\n",
    "#### <a name=\"provide-alternate-accessor-to-collections\"></a>当为集合提供存取器时，尽量支持索引值为 `nil` 的访问形式。<sup>[[link](#provide-alternate-accessor-to-collections)]</sup>\n",
    "\n",
    "```ruby\n",
    "# 差\n",
    "def awesome_things\n",
    "  @awesome_things\n",
    "end\n",
    "\n",
    "# 好\n",
    "def awesome_things(index = nil)\n",
    "  if index && @awesome_things\n",
    "    @awesome_things[index]\n",
    "  else\n",
    "    @awesome_things\n",
    "  end\n",
    "end\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## 数值\n",
    "\n",
    "#### <a name=\"integer-type-checking\"></a>通过 `Integer` 检查对象是否是数值类型，而不是 `Fixnum` 或 `Bignum`。因为 `Fixnum` 或 `Bignum` 表达的数值大小存在范围限定。<sup>[[link](#integer-type-checking)]</sup>\n",
    "\n",
    "`Ruby 2.4`已经移除了 `Bignum` 和 `Fixnum`，统一使用 `Integer`。\n",
    "\n",
    "```ruby\n",
    "timestamp = Time.now.to_i\n",
    "\n",
    "# 差\n",
    "timestamp.is_a? Fixnum\n",
    "timestamp.is_a? Bignum\n",
    "\n",
    "# 好\n",
    "timestamp.is_a? Integer\n",
    "```\n",
    "\n",
    "#### <a name=\"random-numbers\"></a>对于随机数的生成，倾向使用 Range 来表示，而不是 Integer + 偏移量，这样可以更加清晰地表达你的意图，类比于投掷骰子。<sup>[[link](#random-numbers)]</sup>\n",
    "\n",
    "```ruby\n",
    "# 差\n",
    "rand(6) + 1\n",
    "\n",
    "# 好\n",
    "rand(1..6)\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## 字符串\n",
    "\n",
    "#### <a name=\"string-interpolation\"></a>倾向使用字符串插值或字符串格式化，而不是字符串拼接。<sup>[[link](#string-interpolation)]</sup>\n",
    "\n",
    "```ruby\n",
    "# 差\n",
    "email_with_name = user.name + ' <' + user.email + '>'\n",
    "\n",
    "# 好\n",
    "email_with_name = \"#{user.name} <#{user.email}>\"\n",
    "\n",
    "# 好\n",
    "email_with_name = format('%s <%s>', user.name, user.email)\n",
    "```\n",
    "\n",
    "#### <a name=\"consistent-string-literals\"></a>使用统一的风格创建字符串字面量。在 Ruby 社区中存在两种流行的风格：默认单引号（风格 A）与默认双引号（风格 B）。<sup>[[link](#consistent-string-literals)]</sup>\n",
    "\n",
    "* **（风格 A）** 当你不需要字符串插值或特殊字符（比如 `\\t`、`\\n`、`'`）时，倾向使用单引号。\n",
    "\n",
    "```ruby\n",
    "# 差\n",
    "name = \"Bozhidar\"\n",
    "\n",
    "# 好\n",
    "name = 'Bozhidar'\n",
    "```\n",
    "\n",
    "* **（风格 B）** 除非字符串中包含双引号，或是你希望抑制转义字符，否则倾向使用双引号。\n",
    "\n",
    "```ruby\n",
    "# 差\n",
    "name = 'Bozhidar'\n",
    "\n",
    "# 好\n",
    "name = \"Bozhidar\"\n",
    "```\n",
    "\n",
    "本指南使用第一种风格。\n",
    "\n",
    "#### <a name=\"no-character-literals\"></a>不要使用 `?x` 字面量语法。在 Ruby 1.9 之后，`?x` 与 `'x'`（只包含单个字符的字符串）是等价的。<sup>[[link](#no-character-literals)]</sup>\n",
    "\n",
    "```ruby\n",
    "# 差\n",
    "char = ?c\n",
    "\n",
    "# 好\n",
    "char = 'c'\n",
    "```\n",
    "\n",
    "#### <a name=\"curlies-interpolate\"></a>不要忘记使用 `{}` 包裹字符串插值中的实例变量或全局变量。<sup>[[link](#curlies-interpolate)]</sup>\n",
    "\n",
    "```ruby\n",
    "class Person\n",
    "  attr_reader :first_name, :last_name\n",
    "\n",
    "  def initialize(first_name, last_name)\n",
    "    @first_name = first_name\n",
    "    @last_name = last_name\n",
    "  end\n",
    "\n",
    "  # 差 - 语法正确，但略显笨拙\n",
    "  def to_s\n",
    "    \"#@first_name #@last_name\"\n",
    "  end\n",
    "\n",
    "  # 好\n",
    "  def to_s\n",
    "    \"#{@first_name} #{@last_name}\"\n",
    "  end\n",
    "end\n",
    "\n",
    "$global = 0\n",
    "\n",
    "# 差\n",
    "puts \"$global = #$global\"\n",
    "\n",
    "# 好\n",
    "puts \"$global = #{$global}\"\n",
    "```\n",
    "\n",
    "#### <a name=\"no-to-s\"></a>在字符串插值中，不要显式调用 `Object#to_s` 方法，Ruby 会自动调用它。<sup>[[link](#no-to-s)]</sup>\n",
    "\n",
    "```ruby\n",
    "# 差\n",
    "message = \"This is the #{result.to_s}.\"\n",
    "\n",
    "# 好\n",
    "message = \"This is the #{result}.\"\n",
    "```\n",
    "\n",
    "#### <a name=\"concat-strings\"></a>当你需要构造巨大的数据块时，避免使用 `String#+`，使用 `String#<<` 来替代。<sup>[[link](#concat-strings)]</sup>\n",
    "\n",
    "`String#<<` 通过修改原始对象进行拼接工作，其比 `String#+` 效率更高，因为后者需要产生一堆新的字符串对象。\n",
    "\n",
    "\n",
    "```ruby\n",
    "# 差\n",
    "html = ''\n",
    "html += '<h1>Page title</h1>'\n",
    "\n",
    "paragraphs.each do |paragraph|\n",
    "  html += \"<p>#{paragraph}</p>\"\n",
    "end\n",
    "\n",
    "# 好 - 并且效率更高\n",
    "html = ''\n",
    "html << '<h1>Page title</h1>'\n",
    "\n",
    "paragraphs.each do |paragraph|\n",
    "  html << \"<p>#{paragraph}</p>\"\n",
    "end\n",
    "```\n",
    "\n",
    "#### <a name=\"dont-abuse-gsub\"></a>当存在更快速、更专业的替代方案时，不要使用 `String#gsub`。<sup>[[link](#dont-abuse-gsub)]</sup>\n",
    "\n",
    "```ruby\n",
    "url = 'http://example.com'\n",
    "str = 'lisp-case-rules'\n",
    "\n",
    "# 差\n",
    "url.gsub('http://', 'https://')\n",
    "str.gsub('-', '_')\n",
    "\n",
    "# 好\n",
    "url.sub('http://', 'https://')\n",
    "str.tr('-', '_')\n",
    "```\n",
    "\n",
    "### <a name=\"heredocs\"></a>heredocs 中的多行文本会保留各行的前导空白。因此做好如何缩排的规划。<sup>[[link](#heredocs)]</sup>\n",
    "\n",
    "```ruby\n",
    "code = <<-END.gsub(/^\\s+\\|/, '')\n",
    "  |def test\n",
    "  |  some_method\n",
    "  |  other_method\n",
    "  |end\n",
    "END\n",
    "# => \"def test\\n  some_method\\n  other_method\\nend\\n\"\n",
    "```\n",
    "\n",
    "#### <a name=\"squiggly-heredocs\"></a>使用 Ruby 2.3 新增的 `<<~` 操作符来缩排 heredocs 中的多行文本。<sup>[[link](#squiggly-heredocs)]</sup>\n",
    "\n",
    "```ruby\n",
    "# 差 - 使用 Powerpack 程序库的 String#strip_margin\n",
    "code = <<-END.strip_margin('|')\n",
    "  |def test\n",
    "  |  some_method\n",
    "  |  other_method\n",
    "  |end\n",
    "END\n",
    "\n",
    "# 差\n",
    "code = <<-END\n",
    "def test\n",
    "  some_method\n",
    "  other_method\n",
    "end\n",
    "END\n",
    "\n",
    "# 好\n",
    "code = <<~END\n",
    "  def test\n",
    "    some_method\n",
    "    other_method\n",
    "  end\n",
    "END\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## 日期与时间\n",
    "\n",
    "#### <a name=\"no-datetime\"></a>避免使用 `DateTime`，除非你确实需要处理历法改革（儒略/格里历的改革），此时通过设置 `start` 参数来明确你的意图。<sup>[[link](#no-datetime)]</sup>\n",
    "\n",
    "```ruby\n",
    "# 差 - 使用 DateTime 表示当前时间\n",
    "DateTime.now\n",
    "\n",
    "# 好 - 使用 Time 表示当前时间\n",
    "Time.now\n",
    "\n",
    "# 差 - 使用 DateTime 表示近现代日期\n",
    "DateTime.iso8601('2016-06-29')\n",
    "\n",
    "# 好 - 使用 Date 表示近现代日期\n",
    "Date.iso8601('2016-06-29')\n",
    "\n",
    "# 好 - 使用 DateTime 表示日期，通过设置 start 参数为 Date::ENGLANG 明确表示使用 England 历法改革版本\n",
    "DateTime.iso8601('1751-04-23', Date::ENGLAND)\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## 正则表达式\n",
    "\n",
    "> 有些人在面对问题时，不经大脑便认为，“我知道，这里该用正则表达式”。现在他要面对两个问题了。<br>\n",
    "> ——Jamie Zawinski"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### <a name=\"no-regexp-for-plaintext\"></a>如果只是在字符串中进行简单的文本搜索，不要使用正则表达式，比如 `string['text']`。<sup>[[link](#no-regexp-for-plaintext)]</sup>\n",
    "\n",
    "#### <a name=\"regexp-string-index\"></a>对于简单的构建操作，使用正则表达式作为索引即可。<sup>[[link](#regexp-string-index)]</sup>\n",
    "\n",
    "```ruby\n",
    "match = string[/regexp/]             # 获取匹配的内容\n",
    "first_group = string[/text(grp)/, 1] # 获取匹配的分组（grp）的内容\n",
    "string[/text (grp)/, 1] = 'replace'  # string => 'text replace'\n",
    "```\n",
    "\n",
    "#### <a name=\"non-capturing-regexp\"></a>当你不需要分组结果时，使用非捕获组。<sup>[[link](#non-capturing-regexp)]</sup>\n",
    "\n",
    "\n",
    "```ruby\n",
    "# 差 \n",
    "/(first|second)/\n",
    "\n",
    "# 好\n",
    "/(?:first|second)/\n",
    "```\n",
    "\n",
    "#### <a name=\"no-perl-regexp-last-matchers\"></a>避免使用 Perl 风格的、用以代表最近的捕获组的特殊变量（比如 `$1`、`$2` 等）。使用 `Regexp.last_match(n)` 来替代。<sup>[[link](#no-perl-regexp-last-matchers)]</sup>\n",
    "\n",
    "```ruby\n",
    "/(regexp)/ =~ string\n",
    "...\n",
    "\n",
    "# 差\n",
    "process $1\n",
    "\n",
    "# 好\n",
    "process Regexp.last_match(1)\n",
    "```\n",
    "\n",
    "#### <a name=\"no-numbered-regexes\"></a>避免使用数字来获取分组。因为很难明白它们代表的含义。使用命名分组来替代。<sup>[[link](#no-numbered-regexes)]</sup>\n",
    "\n",
    "```ruby\n",
    "# 差\n",
    "/(regexp)/ =~ string\n",
    "...\n",
    "process Regexp.last_match(1)\n",
    "\n",
    "# 好\n",
    "/(?<meaningful_var>regexp)/ =~ string\n",
    "...\n",
    "process meaningful_var\n",
    "```\n",
    "\n",
    "#### <a name=\"limit-escapes\"></a>在字符类别中，只有少数几个你需要特别关心的特殊字符：`^`、`-`、`\\`、`]`，所以你不需要转义 `[]` 中的 `.` 与中括号。<sup>[[link](#limit-escapes)]</sup>\n",
    "\n",
    "#### <a name=\"caret-and-dollar-regexp\"></a>小心使用 `^` 与 `$`<sup>[[link](#caret-and-dollar-regexp)]</sup>\n",
    "\n",
    "它们匹配的是一行的开始与结束，而不是字符串的开始与结束。如果你想要匹配整个字符串，使用 `\\A` 与 `\\z`。(注意，`\\Z` 实为 `/\\n?\\z/`)\n",
    "\n",
    "\n",
    "```ruby\n",
    "string = \"some injection\\nusername\"\n",
    "string[/^username$/]   # 匹配成功\n",
    "string[/\\Ausername\\z/] # 匹配失败\n",
    "```\n",
    "\n",
    "#### <a name=\"comment-regexes\"></a>对于复杂的正则表达式，使用 `x` 修饰符。这种做法不但可以提高可读性，而且允许你加入必要的注释。注意的是，空白字符会被忽略。<sup>[[link](#comment-regexes)]</sup>\n",
    "\n",
    "```ruby\n",
    "regexp = /\n",
    "  start         # some text\n",
    "  \\s            # white space char\n",
    "  (group)       # first group\n",
    "  (?:alt1|alt2) # some alternation\n",
    "  end\n",
    "/x\n",
    "```\n",
    "\n",
    "#### <a name=\"gsub-blocks\"></a>对于复杂的替换，使用 `sub/gsub` 与哈希或区块组合的调用形式。<sup>[[link](#gsub-blocks)]</sup>\n",
    "\n",
    "```ruby\n",
    "words = 'foo bar'\n",
    "words.sub(/f/, 'f' => 'F') # => 'Foo bar'\n",
    "words.gsub(/\\w+/) { |word| word.capitalize } # => 'Foo Bar'\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## 百分号字面量\n",
    "\n",
    "#### <a name=\"percent-q-shorthand\"></a>只有当字符串中同时存在插值与双引号，且是单行时，才使用 `%()`（`%Q` 的简写形式）。多行字符串，倾向使用 heredocs。<sup>[[link](#percent-q-shorthand)]</sup>\n",
    "\n",
    "```ruby\n",
    "# 差 - 不存在插值\n",
    "%(<div class=\"text\">Some text</div>)\n",
    "# 应当使用 '<div class=\"text\">Some text</div>'\n",
    "\n",
    "# 差 - 不存在双引号\n",
    "%(This is #{quality} style)\n",
    "# 应当使用 \"This is #{quality} style\"\n",
    "\n",
    "# 差 - 多行字符串\n",
    "%(<div>\\n<span class=\"big\">#{exclamation}</span>\\n</div>)\n",
    "# 应当使用 heredocs\n",
    "\n",
    "# 好 - 同时存在插值与双引号，且是单行字符串\n",
    "%(<tr><td class=\"name\">#{name}</td>)\n",
    "  ```\n",
    "\n",
    "#### <a name=\"percent-q\"></a>避免使用 `%()` 或 `%q`，除非字符串同时存在 `'` 与 `\"`。优先考虑更具可读性的常规字符串，除非字符串中存在大量需要转义的字符。<sup>[[link](#percent-q)]</sup>\n",
    "\n",
    "```ruby\n",
    "# 差\n",
    "name = %q(Bruce Wayne)\n",
    "time = %q(8 o'clock)\n",
    "question = %q(\"What did you say?\")\n",
    "\n",
    "# 好\n",
    "name = 'Bruce Wayne'\n",
    "time = \"8 o'clock\"\n",
    "question = '\"What did you say?\"'\n",
    "quote = %q(<p class='quote'>\"What did you say?\"</p>)\n",
    "```\n",
    "\n",
    "#### <a name=\"percent-r\"></a>只有当正则表达式中存在一个或以上的 `/` 字符时，才使用 `%r`。<sup>[[link](#percent-r)]</sup>\n",
    "\n",
    "```ruby\n",
    "# 差\n",
    "%r{\\s+}\n",
    "\n",
    "# 好\n",
    "%r{^/(.*)$}\n",
    "%r{^/blog/2011/(.*)$}\n",
    "```\n",
    "\n",
    "#### <a name=\"percent-x\"></a>除非调用的命令使用了反引号（这种情况并不多见），否则不要使用 `%x`。<sup>[[link](#percent-x)]</sup>\n",
    "\n",
    "```ruby\n",
    "# 差\n",
    "date = %x(date)\n",
    "\n",
    "# 好\n",
    "date = `date`\n",
    "echo = %x(echo `date`)\n",
    "```\n",
    "\n",
    "#### <a name=\"percent-s\"></a>避免使用 `%s`。倾向使用 `:\"some string\"` 来创建含有空白字符的符号。<sup>[[link](#percent-s)]</sup>\n",
    "\n",
    "#### <a name=\"percent-literal-braces\"></a>针对不同的百分号字面量，使用不同的括号类型。<sup>[[link](#percent-literal-braces)]</sup>\n",
    "\n",
    "  - 针对构建字符串的 `%q`, `%Q` 字面量，使用 `()`。\n",
    "  - 针对构建数组的 `%w`, `%i`, `%W`, `%I` 字面量，使用 `[]`，以与常规的数组字面量保持一致。\n",
    "  - 针对构建正则的 `%r` 字面量，使用 `{}`，此乃惯例。\n",
    "  - 针对 `%s`, `%x` 等其他字面量，使用 `()`。\n",
    "\n",
    "```ruby\n",
    "# 差\n",
    "%q{\"Test's king!\", John said.}\n",
    "\n",
    "# 好\n",
    "%q(\"Test's king!\", John said.)\n",
    "\n",
    "# 差\n",
    "%w(one two three)\n",
    "%i(one two three)\n",
    "\n",
    "# 好\n",
    "%w[one two three]\n",
    "%i[one two three]\n",
    "\n",
    "# 差\n",
    "%r((\\w+)-(\\d+))\n",
    "%r{\\w{1,2}\\d{2,5}}\n",
    "\n",
    "# 好\n",
    "%r{(\\w+)-(\\d+)}\n",
    "%r|\\w{1,2}\\d{2,5}|\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## 元编程\n",
    "\n",
    "#### <a name=\"no-needless-metaprogramming\"></a>避免无谓的元编程。<sup>[[link](#no-needless-metaprogramming)]</sup>\n",
    "\n",
    "#### <a name=\"no-monkey-patching\"></a>当编写程序库时，不要使核心类混乱（不要使用 monkey patch）。<sup>[[link](#no-monkey-patching)]</sup>\n",
    "\n",
    "#### <a name=\"block-class-eval\"></a>对于 `class_eval` 方法，倾向使用区块形式，而不是字符串插值形式。<sup>[[link](#block-class-eval)]</sup>\n",
    "\n",
    "- 当使用字符串插值形式时，总是提供 `__FILE__` 及 `__LINE__`，以使你的调用栈看起来具有意义：\n",
    "\n",
    "    ```ruby\n",
    "    class_eval 'def use_relative_model_naming?; true; end', __FILE__, __LINE__\n",
    "    ```\n",
    "\n",
    "- 倾向使用 `define_method` 而不是 `class_eval { def ... }`\n",
    "\n",
    "#### <a name=\"eval-comment-docs\"></a>当使用 `class_eval`（或其他的 `eval`）的字符串插值形式时，添加一个注释区块来说明它是如何工作的（来自 Rails 代码中的技巧）。<sup>[[link](#eval-comment-docs)]</sup>\n",
    "\n",
    "```ruby\n",
    "# 摘录自 activesupport/lib/active_support/core_ext/string/output_safety.rb\n",
    "UNSAFE_STRING_METHODS.each do |unsafe_method|\n",
    "  if 'String'.respond_to?(unsafe_method)\n",
    "    class_eval <<-EOT, __FILE__, __LINE__ + 1\n",
    "      def #{unsafe_method}(*params, &block)       # def capitalize(*params, &block)\n",
    "        to_str.#{unsafe_method}(*params, &block)  #   to_str.capitalize(*params, &block)\n",
    "      end                                         # end\n",
    "\n",
    "      def #{unsafe_method}!(*params)              # def capitalize!(*params)\n",
    "        @dirty = true                             #   @dirty = true\n",
    "        super                                     #   super\n",
    "      end                                         # end\n",
    "    EOT\n",
    "  end\n",
    "end\n",
    "```\n",
    "\n",
    "#### <a name=\"no-method-missing\"></a>避免使用 `method_missing`。<sup>[[link](#no-method-missing)]</sup>\n",
    "\n",
    "它会使你的调用栈变得凌乱；其方法不被罗列在 `#methods` 中；拼错的方法可能会默默地工作（`nukes.launch_state = false`）。优先考虑使用委托、代理、或是 `define_method` 来替代。如果你必须使用 `method_missing` 的话，务必做到以下几点：\n",
    "\n",
    "  - 确保[同时定义了 `respond_to_missing?`](http://blog.marc-andre.ca/2010/11/methodmissing-politely.html)。\n",
    "  - 仅仅捕获那些具有良好语义前缀的方法，像是 `find_by_*`——让你的代码愈确定愈好。\n",
    "  - 在语句的最后调用 `super`。\n",
    "  - 委托到确定的、非魔术的方法，比如：\n",
    "\n",
    "```ruby\n",
    "# 差\n",
    "def method_missing?(meth, *params, &block)\n",
    "  if /^find_by_(?<prop>.*)/ =~ meth\n",
    "    # ... 一堆处理 find_by 的代码\n",
    "  else\n",
    "    super\n",
    "  end\n",
    "end\n",
    "\n",
    "# 好\n",
    "def method_missing?(meth, *params, &block)\n",
    "  if /^find_by_(?<prop>.*)/ =~ meth\n",
    "    find_by(prop, *params, &block)\n",
    "  else\n",
    "    super\n",
    "  end\n",
    "end\n",
    "\n",
    "# 最好的方式可能是在每个需要支持的属性被声明时，使用 define_method 定义对应的方法\n",
    "```\n",
    "\n",
    "#### <a name=\"prefer-public-send\"></a>倾向使用 `public_send` 而不是 `send`，因为 `send` 会无视 `private/protected` 的可见性。<sup>[[link](#prefer-public-send)]</sup>\n",
    "\n",
    "```ruby\n",
    "module Activatable\n",
    "  extend ActiveSupport::Concern\n",
    "\n",
    "  included do\n",
    "    before_create :create_token\n",
    "  end\n",
    "\n",
    "  private\n",
    "\n",
    "  def reset_token\n",
    "    ...\n",
    "  end\n",
    "\n",
    "  def create_token\n",
    "    ...\n",
    "  end\n",
    "\n",
    "  def activate!\n",
    "    ...\n",
    "  end\n",
    "end\n",
    "\n",
    "class Organization < ActiveRecord::Base\n",
    "  include Activatable\n",
    "end\n",
    "\n",
    "linux_organization = Organization.find(...)\n",
    "\n",
    "# 差 - 会破坏对象的封装性\n",
    "linux_organization.send(:reset_token)\n",
    "\n",
    "# 好 - 会抛出异常\n",
    "linux_organization.public_send(:reset_token)\n",
    "```\n",
    "\n",
    "#### <a name=\"prefer-__send__\"></a>倾向使用 `__send__` 而不是 `send`，因为 `send` 可能会被覆写。<sup>[[link](#prefer-__send__)]</sup>\n",
    "\n",
    "```ruby\n",
    "require 'socket'\n",
    "\n",
    "u1 = UDPSocket.new\n",
    "u1.bind('127.0.0.1', 4913)\n",
    "u2 = UDPSocket.new\n",
    "u2.connect('127.0.0.1', 4913)\n",
    "\n",
    "# 这里不会调用 u2 的 sleep 方法，而是通过 UDP socket 发送一条消息\n",
    "u2.send :sleep, 0\n",
    "\n",
    "# 动态调用 u2 的某个方法\n",
    "u2.__send__ ...\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## 其他\n",
    "\n",
    "#### <a name=\"always-warn\"></a>总是开启 `ruby -w` 选项，以编写安全的代码。<sup>[[link](#always-warn)]</sup>\n",
    "\n",
    "#### <a name=\"no-optional-hash-params\"></a>避免使用哈希作为可选参数。这个方法是不是做太多事了？（对象构造器除外）<sup>[[link](#no-optional-hash-params)]</sup>\n",
    "\n",
    "#### <a name=\"short-methods\"></a>避免单个方法的长度超过 10 行（不计入空行）。理想上，大部分方法应当不超过 5 行。<sup>[[link](#short-methods)]</sup>\n",
    "\n",
    "#### <a name=\"too-many-params\"></a>避免参数列表数目多于三或四个。<sup>[[link](#too-many-params)]</sup>\n",
    "\n",
    "#### <a name=\"private-global-methods\"></a>如果你真的需要“全局”方法，将它们添加到 `Kernel` 并设为私有。<sup>[[link](#private-global-methods)]</sup>\n",
    "\n",
    "#### <a name=\"instance-vars\"></a>使用模块实例变量而不是全局变量。<sup>[[link](#instance-vars)]</sup>\n",
    "\n",
    "```ruby\n",
    "# 差\n",
    "$foo_bar = 1\n",
    "\n",
    "# 好\n",
    "module Foo\n",
    "  class << self\n",
    "    attr_accessor :bar\n",
    "  end\n",
    "end\n",
    "\n",
    "Foo.bar = 1\n",
    "```\n",
    "\n",
    "#### <a name=\"optionparser\"></a>使用 `OptionParser` 来解析复杂的命令行选项。使用 `ruby -s` 来处理琐碎的命令行选项。<sup>[[link](#optionparser)]</sup>\n",
    "\n",
    "#### <a name=\"time-now\"></a>使用 `Time.now` 而不是 `Time.new` 来获取当前的系统时间。<sup>[[link](#time-now)]</sup>\n",
    "\n",
    "#### <a name=\"functional-code\"></a>使用函数式思维编写程序，避免副作用。<sup>[[link](#functional-code)]</sup>\n",
    "\n",
    "#### <a name=\"no-param-mutations\"></a>不要修改参数值，除非那就是这个方法的作用。<sup>[[link](#no-param-mutations)]</sup>\n",
    "\n",
    "#### <a name=\"three-is-the-number-thou-shalt-count\"></a>避免使用三层以上的嵌套区块。<sup>[[link](#three-is-the-number-thou-shalt-count)]</sup>\n",
    "\n",
    "#### <a name=\"be-consistent\"></a>保持一致性。在理想的世界里，遵循这些准则。<sup>[[link](#be-consistent)]</sup>\n",
    "\n",
    "#### <a name=\"common-sense\"></a>使用常识。<sup>[[link](#common-sense)]</sup>"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## 工具\n",
    "\n",
    "以下的一些工具可以帮助你自动检查项目中的 Ruby 代码是否符合这份指南。\n",
    "\n",
    "### RuboCop\n",
    "\n",
    "[RuboCop][] 是一个基于本指南的 Ruby 代码风格检查工具。RuboCop 涵盖了本指南相当大的部分，其同时支持 MRI 1.9 和 MRI 2.0，且与 Emacs 整合良好。\n",
    "\n",
    "### RubyMine\n",
    "\n",
    "[RubyMine](http://www.jetbrains.com/ruby/) 的代码检查[部分基于](http://confluence.jetbrains.com/display/RUBYDEV/RubyMine+Inspections)本指南。\n",
    "\n",
    "[RuboCop]: https://github.com/bbatsov/rubocop"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## 贡献\n",
    "\n",
    "本指南仍在不断改进。某些规则可能缺乏恰当示例，某些规则可能尚未表述到位。任何对这些规则的改进都是对 Ruby 社区的有益帮助。希望在适当时候，这些问题都能够得到解决，暂且铭记于心。\n",
    "\n",
    "这里的每条规则都不是定案。这只是我渴望与同样对 Ruby 编程风格感兴趣的大家一起工作，最终可以为整个 Ruby 社区创造一份有益的资源。欢迎发起讨论或提交一个带有改进性质的更新请求。在此提前感谢你的帮助！\n",
    "\n",
    "你也可以通过 [Gratipay](https://gratipay.com/~bbatsov/) 对此项目（或是 RuboCop）提供财务方面的支持。\n",
    "\n",
    "[![Support via Gratipay](https://cdn.rawgit.com/gratipay/gratipay-badge/2.3.0/dist/gratipay.png)](https://gratipay.com/~bbatsov/)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## 如何贡献？\n",
    "\n",
    "很简单，只需参考[贡献指南](https://github.com/JuanitoFatas/ruby-style-guide/blob/master/CONTRIBUTING.md)。"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## 授权\n",
    "\n",
    "![Creative Commons License](http://i.creativecommons.org/l/by/3.0/88x31.png)\n",
    "本指南基于 [Creative Commons Attribution 3.0 Unported](http://creativecommons.org/licenses/by/3.0/deed.en_US) 授权许可。\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## 口耳相传\n",
    "\n",
    "一份社区驱动的风格指南，如果没多少人知道，对一个社区来说就没有多少用处。微博转发这份指南，分享给你的朋友或同事。我们得到的每个评价、建议或意见都可以让这份指南变得更好一点。而我们想要拥有最好的指南，不是吗？\n",
    "\n",
    "共勉之，<br />\n",
    "[Bozhidar](https://twitter.com/bbatsov)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "[PEP-8]: https://www.python.org/dev/peps/pep-0008/\n",
    "[rails-style-guide]: https://github.com/bbatsov/rails-style-guide\n",
    "[pickaxe]: https://pragprog.com/book/ruby4/programming-ruby-1-9-2-0\n",
    "[trpl]: http://www.amazon.com/Ruby-Programming-Language-David-Flanagan/dp/0596516177\n",
    "[Pandoc]: http://pandoc.org/\n",
    "[RuboCop]: https://github.com/bbatsov/rubocop\n",
    "[rdoc]: http://rdoc.sourceforge.net/doc/"
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Ruby 2.4.1",
   "language": "ruby",
   "name": "ruby"
  },
  "language_info": {
   "file_extension": ".rb",
   "mimetype": "application/x-ruby",
   "name": "ruby",
   "version": "2.4.1"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 2
}