ruby-conventions

Ruby Conventions (Rootstrap)

Apply these conventions whenever producing or modifying Ruby code. Full guide: https://github.com/rootstrap/tech-guides/blob/master/ruby/README.md

Most of these are enforced by RuboCop (see .rubocop.yml). When in doubt, run RuboCop.

Source Code Layout

• UTF-8, Unix line endings, 2-space indentation (no tabs), one expression per line (no ;).
• Max 100 chars per line; end files with a newline; no trailing whitespace.
• Prefer FooError = Class.new(StandardError) over empty class ... end.
• Avoid single-line methods (exception: def no_op; end).
• Spaces around operators, after commas/colons; no spaces inside (, [, around !, or in range literals (1..3).
• Exception: no spaces around exponent: c**2.
• Indent when the same as case.
• Blank lines between methods and around access modifiers; no blank lines inside class/method bodies.
• No trailing comma after last arg/element.
• Spaces around = in default params: def f(a = 1).
• Avoid line continuation \ except for string concatenation.
• In multi-line chains, keep . on the next line.
• Use underscores in big numbers: 1_000_000. Lowercase prefixes 0x, 0o, 0b.
• No block comments (=begin/=end).
• Never more than one consecutive blank line.
• Align multi-line method args after (, OR single-indent with ) on its own line (avoid "double indent").
• For case/if result assignment, either align branches under the keyword or break with kind = on its own line.

Syntax

• Use :: only for constants/constructors, not method calls.
• def with parens when params exist, omit when empty.
• Parens around method arguments, except: no-arg calls, DSL methods (validates :name, ...), and keyword-like (attr_reader, puts).
• Optional args at end of parameter list.
• Prefix unused block vars with _: |_k, v|.
• Avoid parallel assignment (a, b, c = 1, 2, 3) except for swap, method-return destructuring, or splat.
• Prefer trailing-underscore form: a, = foo.split(',') over a, _, _ = .... Use named underscore vars (_second) when position conveys meaning.
• Don't use for; use iterators (each).
• No then in multi-line if; no if x; .... Always put the condition on the same line as if/unless.
• Avoid multi-line ternary — use if/unless instead.
• No while cond do / until cond do for multi-line loops (drop the do).
• Favor ternary over if/then/else one-liners; don't nest ternaries.
• Leverage if/case as expressions.
• Use ! not not; avoid !! boolean coercion.
• and/or keywords are banned — use &&/||.
• Favor modifier if/unless/while/until for single-line bodies; avoid on multi-line blocks; don't nest modifiers.
• Favor unless for negatives; favor until over while for negative loop conditions. Never unless with else.
• No parens around control-expression conditions (except safe assignment if (v = ...)).
• Use Kernel#loop for infinite loops; prefer loop { ... break unless ... } over begin ... end while for post-condition loops.
• Omit outer {} AND parens for internal DSL methods: validates :name, presence: true, length: { within: 1..10 }.
• Omit outer {} on trailing options hashes: user.set(name: 'John', age: 45).
• Use &:method shorthand: names.map(&:upcase).
• {...} for single-line blocks, do...end for multi-line. Avoid do...end in chains.
• Avoid explicit return when unnecessary; avoid self. unless required.
• Use ||= to init nil/unset vars; don't use ||= for booleans.
• Use &&= to preprocess nullable values.
• Avoid === outside case.
• Use == not eql? unless strict type comparison is intended.
• No space between method name and opening paren: f(x).
• No nested method defs; use lambdas.
• Lambda: ->(a, b) { ... } with args (parens required); -> { ... } with no args (omit parens); lambda do ... end for multi-line.
• Prefer proc over Proc.new; use .call() not [] or .().
• Use shorthand self-assignment: x += y, x **= y, etc.
• Use explicit &block to forward blocks rather than wrapping them.
• Don't shadow methods with local variables (e.g. naming an arg options when an accessor already exists).
• Don't use character literals (?x) — use 'x'.
• Avoid Perl-style special vars ($;, $,); prefer English library aliases ($LOAD_PATH, etc.).
• Don't use BEGIN/END blocks; use Kernel#at_exit instead.
• Use warn over $stderr.puts.
• Favor sprintf/format over String#%; Array#join over Array#*.
• Use Array(var) to coerce possibly-single values into arrays.
• Use ranges or between? instead of x >= a && x <= b.
• Predicate methods (.even?, .zero?, .nil?) over == 0, == nil.
• Avoid !x.nil? when if x suffices.
• Guard clauses over nested conditionals; next over if in loops.
• Prefer: map over collect, select over find_all, find over detect, reduce over inject, size over length/count (note: count on non-Array Enumerables iterates the full collection).
• flat_map over map.flatten(1); reverse_each over reverse.each.