chneukirchen / styleguide

This URL has Read+Write access

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