Coding Style Standards

“Programs must be written for people to read, and only incidentally for machines to execute.”

— Harold Abelson

This document serves as a comprehensive guide to enforcing coding conventions in a Ruby on Rails environment at Planet Argon. By adhering to the same conventions set by the Rails community, we ensure the seamless integration of our contributions into our clients’ codebases.

In addition to best practices and convention adoption, we enforce coding style through tools such as RuboCop and linters, which streamline the development process by automating the enforcement of many Ruby, Rails, JavaScript, and CSS best practices.

Ruby on Rails Coding Conventions

We follow the same simple set of coding style conventions used by the Ruby on Rails org:

Two spaces, no tabs (for indentation).
No trailing whitespace. Blank lines should not have any spaces.
Indent and no blank line after private/protected.
Use Ruby >= 1.9 syntax for hashes. Prefer { a: :b } over { :a => :b }.
Prefer &&/|| over and/or.
Prefer class << self over self.method for class methods.
Use my_method(my_arg) not my_method( my_arg ) or my_method my_arg.
Use a = b and not a=b.
Use assert_not methods instead of refute.
Prefer method { do_stuff } instead of method{do_stuff} for single-line blocks.

Ruby Coding Conventions

We follow the conventions set out in the community-driven Ruby Style Guide. This guide “recommends best practices so that real-world Ruby programmers can write code that can be maintained by other real-world Ruby programmers”.

We follow this guide so that our code adheres to high-quality industry standards and so that we better understand what RuboCop, the static code analyzer we use that is based on this guide, is checking for in our code.

If we agree as a team that we want to adhere to a different standard than one outlined in this guide, we will update that standard in our forked PA Ruby Style Guide following our Git workflow standards.

JavaScript Coding Conventions

We follow the conventions set out in the Airbnb JavaScript Style Guide. This guide follows the more modern JavaScript conventions of ES6, such as:

Prefer let and const over var, to ensure we know when and why we’re reassigning references
Use literal syntax (const x = {}) instead of contructors (const x = new Object()) for creating objects and arrays
Use object destructuring when accessing and using multiple object properties
Use single quotes '' for strings
Prefer arrow function notation over anonymous function declarations.
Use parantheses around function arguments.

If we agree as a team that we want to adhere to a different standard than one outlined in this guide, we will update that standard in our forked PA JavaScript Style Guide following our Git workflow standards.

Enforcing Style Conventions

Using RuboCop

Installing RuboCop

Start by adding RuboCop to your Gemfile. You can do this by including the line gem 'rubocop', preferably in the development and test groups. Then, run bundle install to install the gem.
Initialization

After installation, initialize RuboCop in your project by running rubocop --init. This command creates a .rubocop.yml file in your project root, which is the configuration file for RuboCop.
First Run

Execute RuboCop by simply running rubocop in your terminal. This will analyze all the Ruby files in your project and report any offenses.
Reviewing Offenses

RuboCop will list all the style and linting offenses found in your code. Review these offenses to understand what needs to be changed in your codebase to adhere to the recommended style guidelines.

Custom RuboCop Configuration

Modifying .rubocop.yml

You can modify the .rubocop.yml file to enable, disable, or customize various cops (RuboCop’s term for rules). This allows you to tailor the style checks to your project’s specific requirements or preferences.
Excluding Files

Sometimes, you might want to exclude certain files or directories from RuboCop’s analysis. This can be done by adding an Exclude list under each cop in the .rubocop.yml file.
Defining Custom Cops

For project-specific guidelines, you can define custom cops. This involves some advanced understanding of RuboCop and Ruby, but it allows for highly customized style enforcement.
Auto-Correcting Offenses

RuboCop can automatically correct some offenses. Running rubocop -a or rubocop --auto-correct will prompt RuboCop to fix these offenses in your code.

Using ESLint

ESLint is a tool for identifying and reporting on patterns found in ECMAScript/JavaScript code.

Prerequisites: Node.js (^12.22.0, ^14.17.0, or >=16.0.0) built with SSL support. (If you are using an official Node.js distribution, SSL is always built in.)

Installation

You can install and configure ESLint using this command:
Terminal window
```
npm init @eslint/config
```
After that, you can run ESLint on any file or directory like this:
Terminal window
```
./node_modules/.bin/eslint yourfile.js
```
Configuration

After running npm init @eslint/config, you’ll have an .eslintrc file in your directory. In it, you’ll see some rules configured like this:
```
{
    "rules": {
        "semi": ["error", "always"],
        "quotes": ["error", "double"]
    }
}
```
The names "semi" and "quotes" are the names of rules in ESLint. The first value is the error level of the rule and can be one of these values:

"off" or 0 - turn the rule off "warn" or 1 - turn the rule on as a warning (doesn’t affect exit code) "error" or 2 - turn the rule on as an error (exit code will be 1)

The three error levels allow you fine-grained control over how ESLint applies rules (for more configuration options and details, see the configuration docs).