RubyCodingConvention
(DRAFT VERSION: 2001/11/01)
File Names
Directory and File names and Suffixes
Ruby source code
file/directory name is lower case class/module name with suffix '.rb'.
ex.
Foo class => foo.rb
Bar module => bar.rb
FooBar class => foobar.rb (Normal Rule)
foo_bar.rb (Rails Rule)
Foo::Bar class => foo/bar.rb
*1
Libraries
non-standard multiple files required by a script should be in one directory, and they should
be installed to the standard site-ruby directory or a script's library directory.
don't use a current directory for libraries --- it is dangerous. since the directory in which
script exists can not be specified portably, it is also not suited for libraries.
File Organization
• require (if necessary)
• include (if necessary)
• classes and modules definition
• main
• testing code(?) using __FILE__ idiom
ex:
if __FILE__ == $0
<testcode>
end
Beginning Comment
begin - end style
for file header or footer.
=begin
* Name:
* Description
* Author:
* Date:

* License:
=end
using '#' style
for class/module and method definitions
# using foo bar
#
# foo bar buz.
#
class Foo
# bar.bar.bar.
#
class Bar
# constructor of Bar.
#
def initialize(bar = nil)
super(bar)
end
def bar
self
end
end
def initialize()
end
end
Indentation
Line length
Max length is about 80 characters.
Wrapping Line
• Break after comma
• Break after operator
Comments
Ruby has two comments style: =begin...=end and '#'. You should use =begin...=end for
Documentation Comments, and '#' for both Documentation Comments and Implementation
Comments.

Implementation Comments
Block Comments
# Here is block comment.
#
# foo, bar, buz.
Single-Line Comments
# this is single line comment.
## this is also single line comment.
Tailing Comments
if a == 2
true # special case
else
prime?(a) # work only for odd a
end
Documentation Comments
Header/Footer
=begin
= FooBar library
== What's New?
.....
....
== Installation
.....
....
....
=end
In Class/Module
# .....
# ....
#
def foo()
..

or
##
# .....
# ....
#
def foo()
..
Way of no commenting
If you can write simple, short and light scripts, comments may not be necessary.
You can let the script itself tell everything, instead of embedding documentation that may
confuse readers of your script.
Definitions
Initialization
Ruby variables have no 'definitions'. So, you should initialize variables.
One initialization per line
level = 0
size = 0
is preferred over
level = size = 0
Placement
Statements
Simple Statements
Each line should contain at most one statement.
foo = 1 ## Correct
bar = 2 ## Correct
foo = 1; bar = 2 ## AVOID!
Compound Statements
if-end, if-else-end, if-elsif-else-end Statements
simple example:

if <condition>
<statements>
end
more complex example:
if <condition>
<statements>
elsif <condition>
<statements>
else
<statements>
end
You can put on <condition> after <statements> when <statements> is one-line.
<statements> if <condition>
block methods
`{...}' style:
bar.foo(vars){|vars2|
<statements>
}
`do...end' style:
bar.foo(vars) do |vars2|
<statements>
end
one-line block:
bar.foo(){|var| <statements> }
case-when Statements
Ruby's case-when (not when-case) does not need 'break'.
case foo
when condition1
<statements>
when condition2
<statements>
else
<statements>
end
begin-rescue-end Statements
It handles errors (Exceptions).

begin
<statements>
rescue FooError => e
<statements>
rescue BazError => e2
<statements>
rescue
<statements>
end
White Space
Blank Lines
• Between sections of a source file
• Between class and module definitions
• Between methods
• Before blocks or single-line comments
• Between logical sections inside a method to improve readability
Blank spaces
A keyword followed by a parenthesis should be separated by a space.
ex:
while (foo.end?) {
<statements>
}
The number of spaces should be balanced.
a+b ## Correct
a + b ## Correct
a+ b ## AVOID!
a +b ## AVOID! (Erroneous: interpreted as a(+b))
a += b + c
a = (a + b) / (c * d)
a = b
foo(\"foo\" + buz + bar)
Naming Conventions
Classes/Modules
class and module names should be nouns; in mixed case with the first letter of each internal
word capitalized.
ex: class Raster, class Raster::ImageSprite

Methods
Methods should be verbs. All lower case ASCII letters with words separated by underscores
('_')
ex. run(), run_fast(), obj.background_color()
Variables
variable names should be all lower case ASCII letters with words separated by underscore
('_')
ex:
i = 1
some_char = SomeChar.new()
table_width = 0.0
Constants
*2
constants should be all upper case with words separated by underscores ('_').
ex:
MIN_LENGTH = 1
DEFAULT_HOST = \"foo.example.com\"
Omission
Speaking of 'Connection Pool' as a variable, you should decide to prefer name by scope such
as the following...
• 'conpool' for local scope (such as local variable)
• '@connection_pool' for class scope (such as instance variable)
Pragmatic Programming Practices
Using attr_* to access
def foo()
@foo
end
attr_reader :foo
Without Parenthesis
Some methods are used without parenthesis.
• require
ex. require 'foo/bar'
• include

ex. include FooModule
• p
ex. p foo
• attr_*
ex. attr_reader :foo, :bar
Reduce repetition
When successive lines of a script share something,
x = ModuleA::ClassB::method_c( a )
y = ModuleA::ClassB::method_d( b )
(-- 'function' => 'method' --)
you should make it like this:
cb = ModuleA::ClassB
x = cb::method_c( a )
y = cb::method_d( b )
You can also do:
include ModuleA
x = ClassB::method_c(a)
y = ClassB::method_d(b)
Code Example
Ruby Source File Example
=begin
blahdy/blah.rb
$Id:$
Copyright (c) 2001 TAKAHASHI Masayoshi
This is free software; you can copy and distribute and modify
this program under the term of Ruby's License
(http://www.ruby-lang.org/LINCENSE.txt)
=end
#
# module description goes here.
#
# @version: 1.82
# @author: TAKAHASHI Masayoshi
#

module Blahdy
class Blah < SomeClass
# A class implementation comment goes here.
# CLASS_VAR1 documentation comment
CLASS_VAR1 = 1;
# CLASS_VAR2 documentation comment that happens
# to be more than one line length.
#
CLASS_VAR2 = 1;
# ...constructor Blah documentation comment...
#
def initialize()
## ...implementation goes here...
end
# ...method do_something documentation comment...
#
def do_sometiong()
## ...implementation goes here...
end
# ...method do_something_else documentation comment...
#
# @param some_param description
#
def do_something_else(some_param)
## ...implementation goes here...
end
end
end
*1
any arguments?
*2
Huh, is there a reasonable background to distinguish constants from a class name which is a constant at the
same time?