翻译:
itachi007
附件为最终修订版下载.
修订者:drive2me
[url]http://rc.org.cn/?uid/172[/url]
前言
本规约
、
记述的是在用
Ruby
进行编程时所使用的编程规约
。
在实际项目开发的时候,推荐以此为基础,根据项目实际情况进行客户化后再使用。
源代码的
整形
代码缩进
为了增加程序的可读性而进行的适当的缩进,缩进的幅度以
2
个字符为宜。另外,缩进的时候,只可使用空格,不可使用
TAB
(编程工具不同的时候,看起来会不一样)
例
:
if x > 0
if y > 0
puts "x > 0 && y > 0"
end
end
一行的字符数
一行的字符数以
80
字符(半角)为宜
。
空行
用空行来区分开复数的类
正
例
:
class Foo
...
end
class Bar
...
end
误例
:
class Foo
...
end
class Bar
...
end
另外、类中的各个构成要素之间也需要用空行来隔开。
但是,最初的要素之前和最后的要素之后不需要插入空行。
正
例
:
class Foo
attr :bar
def baz
...
end
def quux
..
end
end
误
例
:
class Foo
attr :bar
def baz
...
end
def quux
...
end
end
注释
方法的定义中不需要注释行
。(
需要重构的地方应该加上注释
。)
但是,对类、模块、或公有方法的注释要使用
RDoc
的风格来注释。
例
:
#
コンマ区切の文字列
+str+
を分割し、結果を配列にして返す。
def split_csv(str)
return str.split(/,/)
end
程序结构相关的规约
类的构成要素
类的构成要素以下记的顺序来记述。
- 模块的包含
- 常数的定义
- 类变量、类实例的定义
- 类方法的定义
- 属性方法的定义
- initialize的定义
- 公有实例方法的定义
- 保护类方法的定义
- 保护属性方法的定义
- 保护实例方法的定义
- 私有类方法的定义
- 私有属性方法的定义
- 私有实例方法的定义
- 嵌套类的定义
属性方法
的定义
在
属性方法
的定义中,使用
attr_accessor
、
attr_reader
、
attr_writer
(
不使用
attr
)
方法的定义
方法的定义中,形参要用括号括起来。但是
、
没有参数的时候,括号可以省略。
正
例
:
def foo(x, y)
...
end
def foo
...
end
误
例
:
def foo x, y
...
end
def foo()
...
end
类方法的定义
类方法的定义的时候要使用
self
。
正
例
:
class Foo
def self.foo
...
end
end
误
例
:
class Foo
def Foo.foo
...
end
end
方法调用
调用某个方法的时候,参数要用括号括起来
。
但是,没有参数的时候,括号可以省略。
另外,
print
、
puts
、
p
的时候,也可已省略参数
。
正
例
:
foo(1, "abc")
obj.foo(1, "abc")
bar
print "x = ", x, "\n"
误
例
:
foo 1, "abc"
obj.foo 1, "abc"
bar()
代码块
一个代码块基本上使用
do ... end
来包括起来
正
例
:
foo(x, y) do
...
end
x = bar(y, z) do
...
end
误
例
:
foo(x, y) {
...
}
x = bar(y, z) {
...
}
但是,方法链使用的时候,用
{ ... }
来包括起来。
正
例
:
s = ary.collect { |i| i.to_s }.join(",")
误
例
:
s = ary.collect do |i| i.to_s end.join(",")
return
方法有返回值的时候
、
必须使用
return
来明示
。
另外
、
return
的括号可以省略。
例
:
def add(x, y)
return x + y
end
误
例
:
def add(x, y)
x + y
end
def add(x, y)
return(x + y)
end
yield
yield
的调用方法遵照方法的调用规则
。
条件分支
If
语句的
then
可以省略
。
另外
、
如果是
if !x
的时候
、
请用
unless x
来置换。
但是,
unless
的时候
、
不使用
else
。
还有,非常简单的条件,一行能够写下来的时候,直接使用
if
/
while
也可
。
正
例
:
if x > 0
puts "x > 0"
else
puts "x <= 0"
end
unless x
puts "x is false"
end
puts "x is true" if x
误
例
:
if x > 0 then
puts "x > 0"
end
unless x
puts "x is false"
else
puts "x is true"
end
puts "foo && bar && baz && quux" if foo &&
bar && baz && quux
能使用
case
、
请使用
case
。
省略掉
then
。
正
例
:
case x
when 1
...
when 2
...
end
误
例
:
if x == 1
...
elsif x == 2
...
end
case x
when 1 then
...
when 2 then
...
end
不要直接使用条件分支作为代入值
。
正
例
:
if x > 0
msg = "x > 0"
else
msg = "x <= 0"
end
误
例
:
msg = if x > 0
"x > 0"
else
"x <= 0"
end
循环
While
语句
do
省略
。
另外
、
while !x
的时候
、
请使用
until x
。
正
例
:
while cond
...
end
until cond
...
end
误
例
:
while cond do
...
end
另外
、
无限循环的时候,使用
loop
。
正
例
:
loop do
...
end
误
例
:
while true
...
end
逻辑运算符
逻辑运算中,使用
!
、
&&
、
||
。
(
not
/
and
/
or
不使用
。
)
三项运算符
除非有明确的可读性,尽量不要使用三项运算符
。
特别是
、
括号等必要的条件复杂的时候
、
跨行的时候
、
不使用三项运算符
。
字符串
字符串基本上使用
"..."
的形式
。
但是,只有在某些特殊文字的场合,使用
'...'
的形式
。
另外
、
原则上不使用“
here document
”
命名规约
全体
- 原则上、不建议使用省略的单词。
- 作用域小的变量、i, j, k等单字母,顺序使用。
- 作用域小的变量、使用类名的省略语也没有关系。 (例: eo = ExampleObject.new)
类名和模块名
类以及模块名
、
每个单词的头一个字母大写
、
不要使用
’_’
(下划线)等分隔符
。
但是
、
像
HTTP
这样的通用缩略语,全体大写也可。
正
例
:
ExampleClass
HTTPClient
误
例
:
Example_Class
EXAMPLE_CLASS
HttpClient
HTTPclient
HTTP_Client
方法
名
方法
名は、
全部小写
、
各个单词之间用
’
_
’
分隔
。
方法名中请使用动词的原形。
正
例
:
add_something
误
例
:
addsSomething
Add_Something
返回真假值的方法的命名
、
在动词或形容词后追加
’
?
’
、
形容词的时候,不用添加
’
is_
’
。
正
例
:
visible?
误
例
:
is_visible
is_visible?
另外
、
破坏性和非破坏性的方法都提供的时候
、
在破坏性的方法名后追加
’
!
’
。
例
:
split
split! #
具有破坏性的
split
常数名
类
・
模块
名以外
的常数名
、
全部用大写
、
单词之间用
’
_
’
来分隔
。
例
:
EXAMPLE_CONSTANT
变量名
变量名中
、
全部用小写
、
单词之间用
’
_
’
来分隔。
例
:
tmp
local_variable
@instance_variable
$global_variable
文件名
在文件名中
、
全部使用小写字母
、
单词之间用
’
_
’
来分隔
。
另外
、
可以把文件中主要的类名变成小写后作为文件名来使用
。(
把模块作为命名空间来使用的时候,同时使用目录名,可以体现出构造的阶层来。
)
例
:
foo.rb #
定义了
类
Foo
foo-bar.rb #
定义了
类
FooBar
foo/bar-baz.rb #
定义了
类
Foo::BarBaz
Copyright (C) 2007 Shugo Maeda
licensed under Creative Commons Attribution License