Ruby Style Guide Mastery
Consistent style is a force multiplier. Follow the community-backed Ruby style guide to keep every controller, service, and job readable on day one and day one hundred. These conventions pair perfectly with Rails defaults and the automated checks we run through RuboCop.
Guiding Principles
Readable > Clever: Prefer intention-revealing names, short methods, and guard clauses that highlight the happy path.
Format With Intent
- Two-space indentation (never tabs) for Ruby, ERB, and YAML.
- Hard-wrap code comments at 100 characters to avoid horizontal scrolling.
- Align multiline structures (hashes, arrays, method chains) for quick diff readability.
Prefer Object-Oriented Clarity
- Extract service objects when controller actions exceed ~10 lines.
- Avoid global state; pass collaborators explicitly or inject via initializer.
- Favor composition over inheritance unless subclassing unlocks real reuse.
Formatting Rules That Matter
Whitespace
Surround operators with spaces, keep one blank line between method definitions, and group related private methods with a blank line for scannability.
Collections
Trailing commas on multi-line literals reduce diff noise. Prefer literal syntax (`[]`, `{}`) over Array.new/Hash.new when seeds are known.
Control Flow Patterns
Prefer guard clauses over nested conditionals
Instead of
Write
Guard clauses keep the happy path aligned to the left margin, make conditions discoverable, and pair nicely with early returns in service objects.
Pull Request Style Checklist
Before committing
- Run `bundle exec rubocop`.
- Eliminate trailing whitespace and blank lines at file end.
- Ensure private helpers are grouped under `private`.
During review
- Confirm names describe intent, not implementation.
- Check public methods for YARD or inline docs where necessary.
- Verify tests are named with the scenario + expectation format.
After merging
- Update shared snippets in `doc/` if conventions changed.
- Cross-link new patterns in `AGENTS.md` for assistant guidance.
- Announce notable style shifts in the #engineering Slack channel.
Team Workflow
- Discuss new conventions during engineering huddles; summarize agreements in `doc/RUBY_CONVENTIONS.md`.
- Flag style regressions in code review comments and back them with guide references to keep feedback objective.
- Capture exceptions (e.g., performance-driven deviations) in documentation so the rulebook stays truthful.