Jump To Content

LearnHub




Ruby Coding Convention

RubyCodingConvention

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

:Libraries((any arguments?))

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
      
    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

h4. Block Comments
  # Here is block comment.
  #
  #  foo, bar, buz.
h4. Single-Line Comments
  # this is single line comment.

  ## this is also single line comment.
h4. Tailing Comments
  if a == 2
    true        # special case
  else
    prime?(a)   # work only for odd a
  end
h3. Documentation Comments h4. Header/Footer
  =begin

  = FooBar library

  == What's New?
  .....
  ....

  == Installation
  .....
  ....

  ....

  =end
h4. In Class/Module
  # .....
  # ....
  #
  def foo()
    ..
or
  ##
  # .....
  # ....
  #
  def foo()
    ..
h3. 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 
  
end

more complex example:

if 
  
elsif 
  
else
  
end

You can put on after when is one-line.

if

block methods

`{...}' style:

bar.foo(vars){|vars2|
  
}

`do…end' style:

bar.foo(vars) do |vars2|
  
end

one-line block:

bar.foo(){|var|   }

case-when Statements

Ruby's case-when (not when-case) does not need 'break'.

case foo
when condition1
  
when condition2
  
else
  
end

begin-rescue-end Statements

It handles errors (Exceptions).

begin
  
rescue FooError => e
  
rescue BazError => e2
  
rescue
  
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?) {
  
}

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

constants should be all upper case with words separated by underscores ('_'). ((Huh, is there a reasonable background to distinguish constants from a class name which is a constant at the same time?))

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

h3. 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

Original document


  1. nikosd saidSat, 27 Sep 2008 09:45:01 -0000 ( Link )

    Nice one – pretty comprehensive :)

    Actions
    Vote
    Current Rating
    0
    Rate Up
    Rate Down
    No Votes

    Post Comments

Your Comment
Textile is Enabled (View Reference)