pn-ruby-backend

Ruby / backend rules

Style

• Follow Ruby style: snake_case for methods/variables, PascalCase for classes/modules, SCREAMING_SNAKE for constants.
• Indent with 2 spaces. Use frozen_string_literal: true at the top of all files.
• Prefer explicit returns only at early-exit guard clauses. Avoid implicit returns in multi-branch methods.
• Avoid deeply nested blocks; extract to named methods when nesting exceeds 2 levels.

Rails conventions

• Use Rails conventions before custom abstractions: RESTful resource routes, before_action, scopes, callbacks.
• Controller actions stay thin: validate input, call a service or model method, render result. Business logic belongs in models or service objects, not controllers.
• Service objects for complex operations: plain Ruby objects in app/services/ with a single public #call method.
• Avoid callbacks (before_save, after_create) for side effects that belong in service objects — they make unit testing and debugging opaque.

ActiveRecord and N+1

• Use includes or preload for associations accessed in a loop: User.includes(:orders).
• Use select to limit columns fetched: User.select(:id, :email) — never load full rows when only a subset is needed.
• Use find_each (not all.each) for batch processing: User.find_each(batch_size: 500) { |u| ... }.
• Use the Bullet gem in development to detect and alert on N+1 queries and unused eager loads.

Secrets and config

• All secrets and config from environment variables: ENV["VAR"] or Rails credentials (Rails.application.credentials).
• Use dotenv-rails in development; never commit .env to git. Keep .env.example with placeholder values.
• Never hardcode API keys, tokens, or DB passwords in source, initializers, or YAML config files.

Error handling

• Use begin/rescue with specific exception classes. Never rescue Exception — it catches SignalException (SIGTERM) and SystemExit.
• Raise custom error classes: class PaymentFailed < StandardError; end — allows callers to catch specifically.
• In Rails controllers: use rescue_from for centralized error formatting. Return consistent JSON shapes.
• Use structured logging (Rails logger with semantic_logger or lograge). Include request ID, user ID in log context.