http://pub.cozmixng.org

= 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

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

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

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