Coding Guidelines

(This document is maintained by daniel)

The purpose of these guidelines is to help contributors to write legible code, that integrates with the existing codebase. Most of these were ripped and adapted from http://pub.cozmixng.org/~the-rwiki/rw-cgi.rb?cmd=view;name=RubyCodingConvention

You can probably set your editor to handle most of this

Golden rule

The most important thing is that the code stays human-readable.

Organisation of the code

• There should be one class per ruby file.
• The file name should always match the class name in the standard Rails way. (e.g. some_class.rb for the SomeClass? class)
• For model classes: Relationship and validation should be at the beginning of the file
• Public methods go first, protected and private after that

Indentation

• Indentation is 2 spaces for each level
• Indentation is spaces only. No tabs.

Formatting and Syntax

• If possible, lines should be broken at 80 characters. They may be longer if it helps readability.
• Implied line continuation is possibly confusing. It's better to use the "\" character to mark the continuation explicitly.
• Delimiter-semicolons will not be used. There should never be multiple statements in one line
• Multiple variables should not be initialised in one line

   #!ruby
   foo = 1              # Correct
   bar = 34             # Correct
   foo = bar = 42       # AVOID!
  
   do_something()         # Good
   do_something_else();   # AVOID!
   do_it(); do_more();  # AVOID!!!
  

  Code blocks should generally be define in the do-end-style, not with braces. Braces should be used for trivial one-line blocks

   #!ruby
   foo { |barfoo| bar } # OK
   foo { bar; foobar }  # AVOID! (see above)
   
   foo { |x|            # AVOID
     bar
     foobar
   }
  
   foo do |barfoo|      # Good
     bar
     foobar
   end
  

• There should be spaces around operators
• There should be no spaces before and after opening parentheses

   #!ruby
   a = c * b   # Good
   a=c*b       # AVOID
   
   foo(bar)    # Good
   foo ( bar ) # AVOID
  

• Parentheses around parameter lists shall not be omitted. Excption: import, include and the like and also statements that "tag" classes (e.g. validates_*)
• Parentheses can indicate function calls even for parameter-less functions. However, for accessors and other variable-like methods, they should always be omitted.

   #!ruby
   require "file"        # Ok
   has_many :things      # Ok
   do_something(a, b, c) # Correct
   do_it a               # AVOID this for normal method calls
  
   do_it()               # This syntax is somtimes clearer, but
   do_it                 # this is also o.k. in many cases
   an_object.value       # Obvious
   a_record.valid?       # Good
   a_record.valid?()     # AVOID this, it looks weird
  

• Expressions should always explicitly grouped with parentheses. Not everybody is aware of the precedence rules.

   #!ruby
   a = (a * b) - c  # Good
   a = a * b - c    # AVOID!
  

Naming

• All names should be meaningful.
• Class names: CamelCase, first letter is uppercase (e.g. CarPort)
• Methods: Lowercase, with underscores (e.g. do_something() ). Query methods should end with "?", and methods with side effects and other "dangerous" methods should end with "!"
• Variables: Lowercase, with underscores (e.g. foo_bar)
• Constants: Upercase, with underscores (e.g. MAX_HEIGHT)
• Files: Same as the class name, but lowercase with underscores. Ending with ".rb" (e.g. car_port.rb)

Comments

• All classes and methods should have rdoc-style comments
• Difficult parts should be commented in the code
• Use TODO, FIXME and friends were it makes sense
• If it something requires a lot of explanation, consider refactoring
• If you need to explain general concepts or algorithms, do it outside the code. Insert a reference to the documentation into the code.

Command Expansion and OS calls

Do not directly call OS commands through command expansion or other methods. This is prone to errors and security leaks. Should you need to call external functionality, a proper interface may need to be created.

General considerations

• Classes, Methods and their signatures should be kept short
• Exceptions should only be used for error cases, not for flow control and not for checking conditions
• Don't break the control flow in non-obvious ways