Ruby Coding Style Guides · Ruby China

风格可以用来区分从好到卓越。 -- Bozhidar Batsov
榜样很重要。 -- Officer Alex J. Murphy / RoboCop
有一件事情总是困扰着，作为 Ruby 程序员的我 - python 开发者都有一个很棒的编程风格参考 (PEP-8)，然而我们从没有一个官方的（公认）的 guide，文档化 Ruby 代码风格和最佳实践。而且我信赖这些风格（的作用）。我也相信很棒的 hacker 社区，比如 Ruby 社区，也应该有能力写出这梦寐以求的文档。
这份指南诞生于我们公司内部的 Ruby 编程准则 (由值得你信赖的同志们编写)，我做正在做的工作基于这样的出发点：Ruby 社区的大多数成员会对我正在做的有兴趣这样的发点，并且这个世界上不需要一个公司内部的（编程）准则。一个面向 Ruby 编程的由社区驱动和社区认可一系列的实践，原则和风格形式是有益于大家的。
自从这个 guide（发表）以来，我收到了很多来自世界范围内 Ruby 社区的优秀的成员的回馈。感谢所有的建议和支持！集众家之力，我们可以创作出对每一个 Ruby 开发人员有益的资源。
补充，如果你正在使用 rails 你可能会希望查阅 Ruby on Rails 3 Style Guide。
这个 Ruby 风格指南推荐（一些）最佳实践使得现实世界中的 Ruby 程序员可以写出能够被其他现实世界的 Ruby 程序员维护的代码。一个风格指南反映了真实世界的使用习惯，同时一个风格指南伴随着一个观点那就是它被一些人们抵制因为它可能会导致风险的产生甚至毫无用处 —— 无论它有多好。
这个指南被分为几个相关联的 rules 的几节。我会尝试给 rules 添加合理的解释（如果它被省略那么我假设它相当的明显了）。
我并没有列举所有的 rules - 它们大多数基于我作为一个专业的软件工程师的广泛生涯、回馈和来自 Ruby 社区成员的建议以及各种备受推崇的 Ruby 编程资源，例如 "Programming Ruby 1.9" 和 "The Ruby Programming Language"。
很多地方的实践风格在 Ruby 社区没有一个明确的共识（sring 的字面引用，hash 里面的空格，点号在多行方法链的位置，等等）。在这样的场景中所有流行的风格都是被承认的并且它取决于你的选择和考虑。
这个指南仍然在工作进程中 - 一些 rules 缺乏例子，一些 rules 没有合适的例子来使得它们足够明了。在这期间一些问题将会提出 - just keep them in mind for now (以后将得到解决).
你可以使用 Transmuter. 来生成指南的 PDF 或者 HTML 副本。
RuboCop 是一个代码分析器，它基于这个指南。
所有风格都又丑又难读，自己的除外。几乎人人都这样想。 把“自己的除外”拿掉，他们或许是对的... -- Jerry Coffin (on indentation 缩进)
每个缩进级别使用两个 spaces （又名软 tabs）. 不要硬 tabs
使用 Unix-风格 换行符。(*BSD/Solaris/Linux/OSX 用户被为默认涵盖，Windows 用户必须特别小心.)
\n是换行，英文是 LineFeed，ASCII 码是 0xA。 \r是回车，英文是 Carriage Return ,ASCII 码是 0xD。 windows 下 enter 是 \n\r,unix 下是\n,mac 下是\r
不用使用 ; 来分割语句和表达式。以此推论 - 一行使用一个表达式
对于没有内容的类定义，尽可能使用单行类定义形式。
避免单行方法。即便还是会受到一些人的欢迎，这里还是会有一些古怪的语法用起来很容易犯错. 无论如何 - 应该一行不超过一个单行方法。
操作符旁的空格，在逗号，冒号和分号后；在 { 旁和在 } 之前，大多数空格可能对 Ruby 解释（代码）无关，但是它的恰当使用是让代码变得易读的关键。
{ 和 } 值得额外的澄清，自从它们被用于 块 和 hash 字面量，以及以表达式的形式嵌入字符串。 对于 hash 字面量两种风格是可以接受的。
第一种稍微更具可读性（并且争议的是一般在 Ruby 社区里面更受欢迎）。 第二种可以增加了 块 和 hash 可视化的差异。 无论你选哪一种都行 - 但是最好保持一致。
第一种风格极为流行并且通常建议你与之靠拢。第二种，在另一方面，（有争议）更具可读性。 如同 hash - 选取一个风格并且保持一致。
没有空格 (, [之后或者 ], )之前。
when和case 缩进深度一致。我知道很多人会不同意这点，但是它是"The Ruby Programming Language" 和 "Programming Ruby"中公认的风格。
当赋值一个条件表达式的结果给一个变量时，保持分支的缩排在同一层。
在方法定义之间使用空行并且一个方法根据逻辑段来隔开。
避免在一个方法调用的最后一个参数有逗号，特别是当参数不在另外一行。
当给方法的参数赋默认值时，在 = 两边使用空格：
虽然几本 Ruby 书建议用第一个风格，不过第二个风格在实践中更为常见（并可争议地可读性更高一点）。
避免在不需要的时候使用行继续符 \ 。实践中， 除非用于连接字符串，否则避免在任何情况下使用行继续符。
采用连贯的多行方法链式风格。在 Ruby 社区有两种受欢迎的风格，它们都被认为很好 - . 开头 (选项 A) 和 尾随 . (选项 B) 。
(选项 A) 当一个链式方法调用需要在另一行继续时，将 . 放在第二行。
(选项 B) 当在另一行继续一个链式方法调用，将 . 放在第一行来识别要继续的表达式。
在这里可以发现有关这两个另类风格的优点的讨论。
如果一个方法调用的跨度超过了一行，对齐它们的参数。当参数对齐因为行宽限制而不合适， 在第一行之后单缩进也是可以接受的。
对齐多行跨度的 array literals 的元素。
使用 RDoc 以及它的惯例来撰写 API 文档。注解区块及 def 不要用空行隔开。
不要使用区块注释。它们不能由空白引导（=begin 必须顶头开始），并且不如普通注释容易辨认。