public
Last active

Ruby Style Guide

  • Download Gist
gistfile1.txt
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183
Original Source: https://github.com/chneukirchen/styleguide
 
= Christian Neukirchen's Ruby Style Guide
 
You may not like all rules presented here, but they work very well for
me and have helped producing high quality code. Everyone is free to
code however they want, write and follow their own style guides, but
when you contribute to my code, please follow these rules:
 
 
== Formatting:
 
* Use ASCII (or UTF-8, if you have to).
 
* Use 2 space indent, no tabs.
 
* Use Unix-style line endings.
 
* Use spaces around operators, after commas, colons and semicolons,
around { and before }.
 
* No spaces after (, [ and before ], ).
 
* Use two spaces before statement modifiers (postfix
if/unless/while/until/rescue).
 
* Indent when as deep as case.
 
* Use an empty line before the return value of a method (unless it
only has one line), and an empty line between defs.
 
* Use RDoc and its conventions for API documentation. Don't put an
empty line between the comment block and the def.
 
* Use empty lines to break up a long method into logical paragraphs.
 
* Keep lines fewer than 80 characters.
 
* Avoid trailing whitespace.
 
 
== Syntax:
 
* Use def with parentheses when there are arguments.
 
* Never use for, unless you exactly know why.
 
* Never use then.
 
* Use when x; ... for one-line cases.
 
* Use &&/|| for boolean expressions, and/or for control flow. (Rule
of thumb: If you have to use outer parentheses, you are using the
wrong operators.)
 
* Avoid multiline ?:, use if.
 
* Suppress superfluous parentheses when calling methods, but keep them
when calling "functions", i.e. when you use the return value in the
same line.
 
x = Math.sin(y)
array.delete e
 
* Prefer {...} over do...end. Multiline {...} is fine: having
different statement endings (} for blocks, end for if/while/...)
makes it easier to see what ends where. But use do...end for
"control flow" and "method definitions" (e.g. in Rakefiles and
certain DSLs.) Avoid do...end when chaining.
 
* Avoid return where not required.
 
* Avoid line continuation (\) where not required.
 
* Using the return value of = is okay:
 
if v = array.grep(/foo/) ...
 
* Use ||= freely.
 
* Use non-OO regexps (they won't make the code better). Freely use
=~, $0-9, $~, $` and $' when needed.
 
 
== Naming:
 
* Use snake_case for methods.
 
* Use CamelCase for classes and modules. (Keep acronyms like HTTP,
RFC, XML uppercase.)
 
* Use SCREAMING_SNAKE_CASE for other constants.
 
* The length of an identifier determines its scope. Use one-letter
variables for short block/method parameters, according to this
scheme:
 
a,b,c: any object
d: directory names
e: elements of an Enumerable
ex: rescued exceptions
f: files and file names
i,j: indexes
k: the key part of a hash entry
m: methods
o: any object
r: return values of short methods
s: strings
v: any value
v: the value part of a hash entry
x,y,z: numbers
 
And in general, the first letter of the class name if all objects
are of that type.
 
* Use _ or names prefixed with _ for unused variables.
 
* When using inject with short blocks, name the arguments |a, e|
(mnemonic: accumulator, element)
 
* When defining binary operators, name the argument "other".
 
* Prefer map over collect, find over detect, find_all over select,
size over length.
 
 
== Comments:
 
* Comments longer than a word are capitalized and use punctuation.
Use two spaces after periods.
 
* Avoid superfluous comments.
 
 
== The rest:
 
* Write ruby -w safe code.
 
* Avoid hashes-as-optional-parameters. Does the method do too much?
 
* Avoid long methods.
 
* Avoid long parameter lists.
 
* Use def self.method to define singleton methods.
 
* Add "global" methods to Kernel (if you have to) and make them private.
 
* Avoid alias when alias_method will do.
 
* Use OptionParser for parsing complex command line options and
ruby -s for trivial command line options.
 
* Write for 1.8, but avoid doing things you know that will break in 1.9.
 
* Avoid needless metaprogramming.
 
 
== General:
 
* Code in a functional way, avoid mutation when it makes sense.
 
* Do not mutate arguments unless that is the purpose of the method.
 
* Do not mess around in core classes when writing libraries.
 
* Do not program defensively.
(See http://www.erlang.se/doc/programming_rules.shtml#HDR11.)
 
* Keep the code simple.
 
* Don't overdesign.
 
* Don't underdesign.
 
* Avoid bugs.
 
* Read other style guides and apply the parts that don't dissent with
this list.
 
* Be consistent.
 
* Use common sense.

I don't exactly understand some points:

  • Never use then.
    Why? You need "then" for example on one-liners IFs (to avoid ternary operator):
    a = if(b == 20) then 10 else 20 end

  • Using the return value of = is okay: if v = array.grep(/foo/) ...
    No, it's not. You're mixing comparission (if) with assignment (=). It's considered wrong in many other languages (C/C++, Java, JavaScript), even LINT and JSLINT complains, why should be valid in Ruby?

  • Avoid alias when alias_method will do.
    Why?

There are others, but these I really don't understood...

Why? You need "then" for example on one-liners IFs (to avoid ternary operator): a = if(b == 20) then 10 else 20 end

It only said avoid multi-line ternary operator, not ternary operator completely. I have never had a case where I needed then. I use the ternary operator all the time.

a = b == 20 ? 10 : 20 is much cleaner

  • Prefer {...} over do...end. Multiline {...} is fine:

Actually, I think conventional Ruby style is to use {} for only single lines, and do...end for multi-lines

I do not agree with a few of these, especially this one

Write for 1.8, but avoid doing things you know that will break in 1.9.

1.9.2 is my default ruby version and I plan on keeping it that way.

Prefer {...} over do...end. Multiline {...} is fine: having
different statement endings. (} for blocks, end for if/while/...)
makes it easier to see what ends where. But use do...end for
"control flow" and "method definitions" (e.g. in Rakefiles and
certain DSLs.) Avoid do...end when chaining.

I'm agreed with it. do ... end for if/while/..., and {} for block call. if you do do ... end a lot, it will confuse you whether it is a block call or a if/while/... statement.

  • private/public/protected indent
class Foo
  def hello
  end

private

  def world
  end
end
  • naming: &blk for block argument.

  • class method: always use class << self ... end

Please sign in to comment on this gist.

Something went wrong with that request. Please try again.