Sample annotated Rubocop YAML file (Rubocop 0.32.1)

.rubocop-zen.yml

# Last updated: 3 August 2015
#
# Applicable for Rubocop 0.32.1
#
# This document contains a custom Rubocop ruleset adhering to the Clinic-IT Ruby Style Guide (https://github.com/clinic-it/zen/blob/master/guidelines/ruby.md).
#
# All rules from the above are listed, with notes about whether they:
# - are enabled by default
# - require configuration
# - have not been implemented
# - conflict with the community Ruby Style Guide (https://github.com/bbatsov/ruby-style-guide) or Rubocop's default ruleset
#
# Currently not all of the rules in the Clinic-IT style guide can be checked due to conflicts or lack of a matching implementation in Rubocop.
#
# A separate section for unrelated warnings due to Rubocop's default ruleset is at the end of the document; all of them are either disabled or customized.
#
# No conflicts with Rubocop's Rails ruleset have been found as of this writing. The community Rails Style Guide can be found at https://github.com/bbatsov/rails-style-guide


# CONFIGURATION

AllCops:
  Exclude:
    - 'db/**/*'
    - 'config/**/*'
    - 'test/**/*'


# GENERAL

# Limit lines to 80 characters only.
# Enabled by default
# Metrics/LineLength

# Indent using soft indents (2 whitespace) instead of real tab.
# Enabled by default
# Style/IndentationWidth
# Style/Tab

# Avoid trailing whitespace.
# Enabled by default
# Style/TrailingWhitespace

# End each file with newline.
# Enabled by default
# Style/TrailingBlankLines


# OPERATORS

# Whitespace around binary operators.
# Enabled by default
# Style/SpaceAroundOperators
# MultiSpaceAllowedForOperators: =, => (default)

# No whitespace after unary operators.
# Enabled by default
# Style/SpaceAfterNot

# Whitespace after comma.
# Enabled by default
# Style/SpaceAfterComma


# ASSIGNMENT

# Long right-hand expression should start on the next line.
# StyleGuide: https://github.com/clinic-it/zen/blob/master/guidelines/ruby.md#assignment-newline
Style/MultilineOperationIndentation:
  EnforcedStyle: indented

# if-else, case-when, loop, and other multi-line block statements should start on the next line.
# No implementation found
# Ruby Style Guide: https://github.com/bbatsov/ruby-style-guide#indent-conditional-assignment

# Content of large hash value should start on the next line, 1 pair per line.
# Enabled by default: Style/AlignHash, Style/IndentHash
# Cannot check for:
# - having only one key/value pair per line
# - positioning of the braces (Style/IndentHash only requires that the first element is indented relative to the opening curly brace)

# Content of large array value should start on the next line, with each of the succeeding line aligned.
# Enabled by default: Style/AlignArray, Style/IndentArray
# Cannot check for:
# - having as many elements as possible per line/having only one element per line
# - positioning of the brackets (Style/IndentArray only requires that the first element is indented relative to the opening bracket)


# HASH

# Use hash rocket (fat arrow) => instead of colon :.
# StyleGuide: https://github.com/clinic-it/zen/blob/master/guidelines/ruby.md#hash-syntax
Style/HashSyntax:
  EnforcedStyle: hash_rockets
  UseHashRocketsWithSymbolValues: true

# No whitespace around hash body. Curly braces {} with spaces inside will only be used for blocks, in order to make a visual difference between blocks and hashes.
# StyleGuide: https://github.com/clinic-it/zen/blob/master/guidelines/ruby.md#hash-whitespace
Style/SpaceInsideHashLiteralBraces:
  EnforcedStyle: no_space

# 1 key-value pair per line for large hash.
# No implementation found


# ARRAY

# No whitespace around array body.
# Enabled by default
# Style/SpaceInsideBrackets

# Align values for large arrays.
# Enabled by default
# Style/AlignArray


# NUMBERS

# Use _ to promote readability of numbers.
# Enabled by default
# Style/NumericLiterals
# MinDigits: 5 (default)


# STRINGS

# Use single quotes (') by default.
# Use double quotes "" if interpolation is used.
# Enabled by default
# Style/StringLiterals

# Use double quotes "" if you have single quote in your string.
# No implementation found

# Use << instead of + when concatenating strings.
# No implementation found
# Ruby Style Guide: https://github.com/bbatsov/ruby-style-guide#concat-strings

# Use join when concatenating with a uniform delimiter.
# No implementation found

# Use \ to break long strings instead of +.
# Enabled by default
# Style/LineEndConcatenation


# BLOCKS

# Whitespace around body of proc, lambda, and block.
# Enabled by default
# Style/SpaceInsideBlockBraces

# Whitespace before block.
# Enabled by default
# Style/SpaceBeforeBlockBraces

# Use do and end for multi-line blocks.
# Enabled by default
# Style/BlockDelimiters

# Do not use 2 or more consecutive line-break inside blocks.
# Enabled by default: Style/EmptyLines
# Note: Style/EmptyLines checks the entire file; enabling it will include all consecutive empty lines in the list of warnings

# Do not chain multi-line blocks.
# Enabled by default
# Style/MultilineBlockChain


# METHOD

# Method definition should not use parentheses.
# StyleGuide: https://github.com/clinic-it/zen/blob/master/guidelines/ruby.md#method-definition
Style/MethodDefParentheses:
  EnforcedStyle: require_no_parentheses

# 1 Line break to separate method definitions.
# Enabled by default
# Style/EmptyLineBetweenDefs

# Do not use 2 or more consecutive line-break inside methods.
# Enabled by default: Style/EmptyLines
# Note: Style/EmptyLines checks the entire file; enabling it will include all consecutive empty lines in the list of warnings

# Avoid using more than 3 arguments.
# No implementation found

# No space around ().
# StyleGuide: https://github.com/clinic-it/zen/blob/master/guidelines/ruby.md#method-call-paren-space
# Enabled by default
# Style/SpaceInsideParens

# Avoid passing method call as argument.
# No implementation found

# Single-line method call should not use parentheses.
# Enabled by default: Style/MethodCallParentheses
# Note: only checks for method calls with no arguments
# Ruby Style Guide: https://github.com/bbatsov/ruby-style-guide#no-args-no-parens

# Large hash as argument.
# StyleGuide: https://github.com/clinic-it/zen/blob/master/guidelines/ruby.md#method-hash-argument
# Note: does not check parenthesis placement
Style/AlignParameters:
  EnforcedStyle: with_fixed_indentation

# Large array as argument.
# StyleGuide: https://github.com/clinic-it/zen/blob/master/guidelines/ruby.md#method-call-array-arg
# Enabled by default: Style/AlignArray
# Note: Style/AlignArray does not check for bracket placement, only checks if first parameter on each line is aligned

# As much as possible, write 1 argument per line for long argument list.
# No implementation found

# As much as possible, use 1 method call per line for long method chains.
# No implementation found

# Use trailing . for long method chains.
# StyleGuide: https://github.com/clinic-it/zen/blob/master/guidelines/ruby.md#method-chain-trailing
Style/DotPosition:
  EnforcedStyle: trailing


# CONDITIONS

# No parentheses around conditions.
# Enabled by default
# Style/ParenthesesAroundCondition
# AllowSafeAssignment: true (see: https://github.com/bbatsov/ruby-style-guide#safe-assignment-in-condition)

# Do not use 'and' and 'or' on conditions.
# Enabled by default
# Style/AndOr

# Don't use unless with else. Convert to if-else statement.
# Enabled by default
# Style/UnlessElse

# Use early return if possible.
# Enabled by default
# Style/GuardClause
# MinBodyLength: 1 (default)

# Use ternary operator ?: for simple statements instead of if-else.
# Enabled by default: Style/OneLineConditional
# Note: This applies only for if-else blocks that fit on one line

# For long ternary operator ?: statement, write 1 option per line.
# Conflict with Ruby Style Guide: https://github.com/bbatsov/ruby-style-guide#no-multiline-ternary
# Conflict with Rubocop: Style/MultilineTernaryOperator
# Disable to suppress warnings
Style/MultilineTernaryOperator:
  Enabled: false

# 1 expression per line for long condition.
# No implementation found for checking indentation of multiline conditional expression

# For long condition, leave 1 line break before the body.
# No implementation found

# Favor if/else modifier for simple single-line body.
# Enabled by default
# Style/IfUnlessModifier

# Do not use if/else modifier for multi-line blocks.
# No implementation found
# Ruby Style Guide: https://github.com/bbatsov/ruby-style-guide#no-multiline-if-modifiers

# Favor unless over if for negative conditions.
# Enabled by default
# Style/NegatedIf

# Don't use unless for negative expressions.
# No implementation found

# Align when with case.
# Enabled by default
# Style/CaseIndentation

# Multiple expressions alignment.
# No implementation found for checking indentation of multiline conditional expression


# COMMENTS

# Only use multi-line comments for removing a block of code temporarily.
# No implementation found

# Do not use end-of-line comments.
# Implementation seems buggy
# Disabled by default: Style/InlineComment
# Note: Style/InlineComment doesn't discriminate between a commented line and a line containing an inline comment

# Use TODO: to note task that needs to be done on a specific statement or block of code in the future.
# Use SEE: <insert link> if you need to add a reference to a specific statement or block of code.
# Enabled by default: Style/CommentAnnotation
# Note: Style/CommentAnnotation does not check if the keyword SEE is followed by a URL
Style/CommentAnnotation:
  Enabled: true
  Keywords:
  - TODO
  - SEE


# CLASS AND MODULE

# Line break around class and module contents.
# Enabled by default: Style/EmptyLinesAroundClassBody, Style/EmptyLinesAroundModuleBody
Style/EmptyLinesAroundClassBody:
  Enabled: true
  EnforcedStyle: empty_lines

Style/EmptyLinesAroundModuleBody:
  Enabled: true
  EnforcedStyle: empty_lines

# Use 2 line breaks to create logical separations inside class and module.
# Use 3 line breaks to create a logical separation between group of methods inside module/class.
# 5 line breaks between class/module definitions.
# Conflict with Rubocop: Style/EmptyLines
# Note: Style/EmptyLines checks the entire file; enabling it will include all consecutive empty lines in the list of warnings
# Disable to suppress warnings
Style/EmptyLines:
  Enabled: false

# Always use self when calling public and protected properties of a class.
# Conflict with Ruby Style Guide: https://github.com/bbatsov/ruby-style-guide#no-self-unless-required
# Conflict with Rubocop: Style/RedundantSelf
# Disable to suppress warnings
Style/RedundantSelf:
  Enabled: false

# Class statements order.
# No implementation found


# VISIBILITY MODIFIER

# Use protected for utility methods that use instance variables/methods.
# No implementation found

# Use private for utility methods that don't use instance variables/methods.
# No implementation found


# RUBY STYLE GUIDE CONFLICTS
# The ff disable/configure default settings imposed by the Ruby Style Guide or Rubocop itself.

# Avoid methods longer than 10 lines of code.
# https://github.com/bbatsov/ruby-style-guide#short-methods
Metrics/MethodLength:
  Enabled: false

# Checks style of children classes and modules.
# https://github.com/bbatsov/rubocop/issues/868
Style/ClassAndModuleChildren:
  EnforcedStyle: compact

# Document classes and non-namespace modules.
Style/Documentation:
  Enabled: false

# Use the new lambda literal syntax for single-line blocks.
# https://github.com/bbatsov/ruby-style-guide#lambda-multi-line
Style/Lambda:
  Enabled: false

# Use %w or %W for arrays of words.
# https://github.com/bbatsov/ruby-style-guide#percent-w
Style/WordArray:
  Enabled: false