Christian Neukirchen 的 Ruby 编程风格指南

也许你不会同意本文提到的所有规则,但是这些规则确实帮助我产生了高质量的代码,对我来说很有用。任何人都可以随其所想,根据其自己的编码风格去写代码,但是,当你提代码到我的项目里时,请遵守这些规则:

译自:https://github.com/chneukirchen/styleguide

中文版:https://github.com/googollee/styleguide

格式:

  • 使用 ASCII(或者 UTF-8,如果你不得不用的话)。

  • 使用2个空格做缩进,不要用 tab。

  • 使用 Unix 风格的换行做行尾。

  • 在操作符两边,逗号、冒号、分号的后面,{ 的两侧和 } 的前面,加入空格。

  • 在 (、[ 之后和 ]、) 之前没有空格。

  • 在声明修饰符前加入两个空格(在 if/unless/while/until/rescue 的后面)

  • 按照情形进行缩进,不要过多缩进。

  • 在方法的 return 语句前留一个空行(除非只有一行),在 def 前后都留一个 空行。

  • 使用 RDoc 及其约定来写 API 文档。不要在注释块和 def 间留任何空行。

  • 使用空行,将一个很长的方法按逻辑分段。

  • 每行不要超过80个字符。

  • 杜绝行尾空格。

语法:

  • 如果有参数时,def 后面要用括号包住参数。

  • 永远不要用 for,除非你确确实实知道你在做啥。

  • 永远不要用 then 。

  • 在条件语句只有一行的情况下,使用 when x; …

  • 在布尔表达式里使用 &&/||,在程序流程控制里使用 and/or。(小提示:如果你不得不在最外层加括号,那你就用错操作符了。)

  • 杜绝多行使用 ?: ,多行的情况下应该用 if 。

  • 在调用方法的时候,绝不能使用多余的括号(参数最外面不用括号),但是在调用“函数”时使用括号,比如,当你在一行里需要使用函数的返回值。

    x = Math.sin(y)
    array.delete e
  • 使用 {…} 好过 do…end 。多行情况使用 {…} 也很好:可以用不同的结束符标识不同的内容(用 } 标识块,而 end 标识 if/while/… ),这样可以很容易看出到哪里结束。不过在“程序流程控制”和“定义方法”时使用 do…end(比如,在 Rakefiles 和特定的 DSL 里)。在链式调用时杜绝 do…end 。

  • 杜绝无谓的 return。

  • 杜绝无谓的续行符(\)。

  • 可以直接使用 = 运算符返回的值:

    if v = array.grep(/foo/) ...
  • 请自由使用 ||=。

  • 使用非 OO 风格的正则表达式( OO 风格不会让你的代码变得更好)。在需要的时候,自由使用 =~,$0-9,$` 和 $‘。

命名:

  • 方法名使用 snake_case 风格。

  • 类名和模块名使用 CamelCase 风格。(常用首字母缩写保持大写,比如HTTP,RFC,XML)

  • 其他常量使用 SCREAMING_SNAKE_CASE 。

  • 标识符名字的长度决定了其生存周期。在短小的块/方法里,使用单字母变量作为参数,具体名字如下:

    • a,b,c:任意对象
    • d:目录名字
    • e:Enumerable的元素
    • ex:截获的异常
    • f:文件对象和文件名
    • i,j:索引
    • k:哈希项的键值部分
    • m:方法
    • o:任意对象
    • r:短函数的返回值
    • s:字符串
    • v:任意值
    • v:哈希项的值部分(和上面一个有毛区别啊!)
    • x,y,z:数字

    另外,通常来说,如果使用变量时,其值的所有对象都是某个类型,用类名的首字母来表示。

  • 对用不到的变量,使用 _ 或者用 _ 做前缀的名字。

  • 当使用带有短块的注入时,对变量命名 |a, e|(方便助记:累加,元素)

  • 当定义二值操作符时,将第二个参数命名为“other”。

  • 优先使用 map 而不是 collect ,优先使用 find 而不是 detect ,优先使用 find_all 而不是 select ,优先使用 size 而不是 length 。

注释:

  • 比一个单词长的注释,每句话要首字母大写,并且使用标点。每段后用两个空格分隔。

  • 杜绝在注释里灌水。

其他:

  • 写对 ruby -w 安全的代码。

  • 杜绝将哈希表作为可选参数的行为。这个方法是不是干的事情太多了?

  • 杜绝过长的方法。

  • 杜绝太长的参数列表。

  • 使用 def self.method 这种方式定义单例(singleton)方法。

  • 将“全局”方法加入到 Kernel (如果你不得不写“全局”方法的话),并将其设为私有的。

  • 如果 alias_method 可以做,就不要使用 alias 。

  • 使用 OptionParser 来解析复杂的命令行参数,并用 ruby -s 明确指定命令行参数。

  • 在1.8下编码,但不要做任何可能导致在1.9下不可用的事情。(那直接用1.9不就行了)

  • 杜绝没用的元编程。

一般:

  • 用函数编程的方式写代码,如果可行的话就杜绝可变量。

  • 除非函数的意图就是改变参数值,否则不要这么做。

  • 写库的时候,不要把核心类弄乱。

  • 不要使用防御式编程。(参见 http://www.erlang.se/doc/programming_rules.shtml#HDR1

  • 保持代码简单。

  • 别做过度设计。

  • 也别不设计。

  • 杜绝 bugs。(别逗了!)

  • 阅读其他的风格指导,并且接受与本指导不冲突的部分。

  • 保持前后一致。

  • 使用常识。

Googol Lee

多年生软件工程师,信仰开源

Munich, Germany http://air.googol.im