Ruby on Rails Code Guideline

Index

• Language & Framework Versions
• Getting started
• Project README template
• Gems
• Comments
• Style Guidelines
  • Rubocop
• MVC
  • Controllers - Models
  • Views/Rendering
• Tests
  • CircleCI
• Mailer
• Background workers
• Time
• Monitoring
• Deployment

Language & Framework Versions

When creating a new project:

• Use Ruby 2.4.X or higher
• Use Rails 5.2.X

Use the latest patched version, as they contain various fixes and security patches. Same applies to the gems. Use bundler-audit to check if there are any security updates available to the gems you are using.

Getting started

Create all new Rails projects with postgresql database and skip coffeescript

rails new project_name -d postgresql --skip-coffee --skip-turbolinks --skip-test

Add dotenv-rails for reading env values and rspec-rails for use of RSpec test framework. Also add factory_bot and faker. Do not use paperclip, its deprecated, use ActiveStorage instead.

Git ignore .env.* files. Create an empty .env.development for the development environment and .env for general use. Describe in ReadMe which envs are used and why.

Project README template

Example of a project readme template

# Project name

## General
This is the project template for the project that does this and that.

## Requirements
1. Ruby x.x.x
2. Rails x.x.x
3. Postgresql DB
4. ...
<br>

## Environmental variables
Describe what env variables are needed and why

## Logic
Any specific business logic that needs to be described.

## Tests
Testing framework is RSpec. Run tests by `bundle exec rspec` or just `rspec`

Gems

• Don’t use outdated gems
• Use RubyGems when searching for gems.

Comments

• Comment your code
• You don’t need to comment trivial code or code that is easy understandable
• Do comment what a service, worker or a concern for example does if it’s not clearly visible
• Will you know what method X that calls N other methods based on some conditions is supposed to do a year later? Probably not and that means that it will take a lot of time to figure things out again. Spend a little time now to save a lot of time later.

Style Guidelines

While our guidelines describes the basics, do read the full community driven style guidelines for any specific: https://github.com/rubocop-hq/rails-style-guide

Rubocop

Use Rubocop in Rails projects. The circle ci config from CircleCI chapter also assumes that you have rubocop config file read. Default Rubocop complains on newer Rails. Use this starter template and place it in root dir (.rubocop.yml, the rubocop command will pick it up) to get started right away.

AllCops:
  Exclude:
    - 'spec/**/*.rb'
    - 'lib/tasks/**/*.rake'
    - 'config/**/*.rb'
    - 'bin/**/*'
    - 'Gemfile'
    - 'Gemfile.lock'
    - 'app/admin/**/*.rb'
    - 'config.ru'
    - 'db/*.rb'
    - 'app/helpers/*.rb'
    - 'app/mailers/*.rb'
    - 'Rakefile'

Style/FrozenStringLiteralComment:
  Enabled: false

Style/Documentation:
  Enabled: false

MVC

Controllers

• Any business logic should be in models not in controllers
• Each controller action should invoke only one method (if possible)
• Keep controllers “thin”

Models

• You can have non ActiveRecord models/classes here as well
• Group has_many, validations together at the beginning
• Add a dependent option to the has_many and has_one associations
• Use has_many :through instead of has_and_belongs_to_many!
• Use concerns to split up domain specific logic
• All custom validators (if necessary) should be in app/validators

Views/Rendering

• Use partial views to keep views easy to understand, and making reusable components
• Views should not communicate to the model directly! That’s why there are controllers.
• Use view helpers for any complex formatting

Tests

• Write tests, use RSpec, FactoryBot & Faker
• You don’t have to have 100% coverage but majority of the code should be covered
• Write code so it’s easy to be tested. No big chunks.

CircleCI

• Each new project should have a CircleCI setup (check project specifications otherwise)
• Check repository rails-ci-example on Poviolabs GitHub and read the ReadMe of the project.

Mailer

• Use the free MailTrap.io service if you need to test sending the email.

Background workers

• Use solutions on a case by case. As some services may be better at other things.

Time

• Configure your timezone in config/application.rb if you need, the default is UTC
• Run rails time:zones to see all available time zones, choose yours and then set it in config/application.rb
• Don’t use Time.now & Time.parse instead use Time.zone.now & Time.zone.parse as it will use the Timezone and not the server time.

# bad
Time.parse('2015-03-02 19:05:37') # => Will assume time string given is in the system's time zone.

# good
Time.zone.parse('2015-03-02 19:05:37') # => Mon, 02 Mar 2015 19:05:37 EET +02:00

# bad
Time.now # => Returns system time and ignores your configured time zone.

# good
Time.zone.now # => Fri, 12 Mar 2014 22:04:47 EET +02:00
Time.current # Same thing but shorter.

Monitoring

• Heroku:
  • Rollbar
• Google Cloud Platform
  • Stackdriver

Deployment

• Heroku (popular)
• Google App Engine (project specific, it’s more like heroku)
• AWS Beanstalk (project specific, more maintaince required)

Docker

• Check repository rails-ci-example on Poviolabs GitHub and read the ReadMe of the project.
• That project can also be run inside a Docker container with Docker + Docker Compose examples.