rubocop.yml

### TODOs
# TODO: Enforce CamelCase constant names all the way
# TODO: don't chain on multiline blocks (do/end and {})
# TODO: while 120 column lines are fine, there should be a threshold of <=10% being >80 columns
# TODO: only enforce _ in integer literals every 3 digits when no _ is present, but if at least one is present, assume they're correct (to enable e.g. date integers: 2014_05_10)
# TODO: map > collect
# TODO: inject > reduce


### INCLUSIONS/EXLUSIONS

AllCops:
  Exclude:
    - "ruby_gems/*/development/**/*"
    - "ruby_gems/*/documentation/**/*"
    - "ruby_gems/*/docs/**/*"
    - "ruby_gems/vendor/**/*"


### CUSTOMIZATIONS WITH RATIONALE

# Rationale:
# Duck-typing all the way. It does not matter whether a constant is a class/module
# or an arbitrary object.
# See TODOs with regards to enfocing CamelCase
ConstantName:
  Enabled: false

# Rationale:
# do/end blocks should not be used for return values, therefore we should not chain either.
MethodCalledOnDoEndBlock:
  Enabled: true

# Rationale:
# Multiline {} are fine, but don't chain on them (see TODOs)
# We use {} for return value (map, select, inject), do/end for side-effects (each, DSLs)
Blocks:
  Enabled: false

# Rationale: fail is an alias of raise. Avoid aliases, it's more cognitive load for no gain.
SignalException:
  EnforcedStyle: only_raise

# Rationale: We check this using yard, so this is superfluous
Documentation:
  Enabled: false

# Rationale:
# Arrays should look like arrays, therefore array-literals use []
# For scalar literals, {} is preferred over () (not final)
PercentLiteralDelimiters:
  PreferredDelimiters:
    "%":  "{}"
    "%q": "{}"
    "%Q": "{}"
    "%r": "{}"
    "%s": "{}"
    "%x": "{}"
    "%w": "[]"
    "%W": "[]"
    "%i": "[]"
    "%I": "[]"

# Trailing comma in multiline literals are recommended.
# Rationale: makes adding values easier and less error prone
TrailingComma:
  EnforcedStyleForMultiline: comma

# I want this, but collides with alignments in DSLs. I weight that higher.
# Might be a case for strict, to catch offenders which are not offending due to being aligned.
SingleSpaceBeforeFirstArg:
  Enabled: false

# With `ExactNameMatch: false`, rubocop complains about foo? style readers, and about readers
# which return ivars of a different name (the latter might be a code smell, not sure about that yet)
TrivialAccessors:
  ExactNameMatch: true

# This is just silly. Calling the argument `other` in all cases makes no sense.
OpMethod:
  Enabled: false

# This one seems uninformed to me. raise Klass, "message" is the default.
# But a specialized exception class will take one or more arguments and construct the message from it.
# So both variants make sense.
RaiseArgs:
  Enabled: false


### TEMPORARILY DISABLED (until jacob reaches a more stable phase)
Debugger:
  Enabled: false
UnusedMethodArgument:
  Enabled: true



### NON FINALE PREFERENCES

# I want this, but it fails with date integers e.g. 2014_05_10, therefore currently disabled
NumericLiterals:
  Enabled: false

# Rationale:
# I want those two, but rubocop can't deal with deindented public/protected/private/module_function
IndentationConsistency:
  Enabled: false
IndentationWidth:
  Enabled: false

# Rationale:
# Less is more. Just always use double quotes. Only use single quotes or % literal
# when the string should explicitely not be interpolated.
# Contra: An argument in favor of single_quotes is that some consider it easier on the eye.
#         IMO not an argument is "less overhead". This is parse time and the difference is academic at best.
StringLiterals:
  EnforcedStyle: double_quotes

# Can't decide on a style. I see three uses in my code:
# A)
#     attr_accessor :foo,
#                   :bar
#
# B)
#     sprintf "#<%s:%x %p>",
#       self.class,
#       object_id >> 1,
#       @attribtues
#
# C)
#     some_method(
#       arg1,
#       arg2,
#     )
#
# I think all three have their place. Not sure a) whether to pick one and go with it, and b) if so, which one.
# I'd venture for C at the moment. Rationale: less chance of overlength lines. Contra: ugly with DSLs due to required
AlignParameters:
  Enabled: false

# I like to use multiple newlines to separate "topical" content, and to separate the require "header" from the code body.
# However, I'll activate this for now and see how it goes.
EmptyLines:
  Enabled: true

# Not sure about this. Especially with constructors, it's sometimes very hard to do well.
# I'll settle at the moment to enforce moving too many arguments to kwargs
ParameterLists:
  Max: 5
  CountKeywordArgs: false

# Not sure about this. I like giving the body space. I find it more legible. Especially with nested classes.
# However, I'll activate this for now and see how it goes.
EmptyLinesAroundBody:
  Enabled: true

# Reducing aliases is good. But sprintf is non-OO and % is sometimes annoying to use because you have to construct
# an array first. Kernel#format is IMO the worst choice, as it is neither OO, nor is it as widely known as sprintf.
# (Though I admit that sprintf is an archaic and ugly name)
# Keeping it currently disabled.
FormatString:
  Enabled: false
  EnforcedStyle: percent


### STYLE PREFERENCES WITHOUT RATIONALE

# Style preference
SpaceAroundEqualsInParameterDefault:
  EnforcedStyle: no_space

# Style preference
SpaceInsideHashLiteralBraces:
  EnforcedStyle: no_space

# Style preference
CaseIndentation:
  IndentWhenRelativeTo: end
  IndentOneStep: true
  Enabled: true


## VALUES WHICH SHOULD DIFFER IN .rubocop-strict.yml

# Rationale:
# We are not in the dark ages of 80 column terminals any more.
# Short lines are good for readability, but occasional longer lines are not damaging.
# See TODOs with regards to thresholds.
LineLength:
  Max: 120 # strict: 80 - check against threshold

# Rationale:
# We assume jacob devs know the proper use of .nil?, and jacob itself has legitimate uses of it
NonNilCheck:
  Enabled: false # strict: true - find illegitimate uses of .nil?

# Rationale:
# Too short methods lead to extraction of single-use methods, which can make the code easier to read (by naming things),
# but can also clutter the class
MethodLength:
  Max: 50 # - strict: 20 - find candidates for refactoring

# Rationale:
# The guiding principle of classes is SRP, SRP can't be accurately measured by LoC
ClassLength:
  Max: 1500 # strict: 250 - find candidates for refactoring

# Rationale:
# We assume jacob devs know the proper use of ===, and jacob itself has legitimate uses of it
CaseEquality:
  Enabled: false # - strict: true - find illegitimate uses of ===

# I need more experience with this.
# I think this too should be threshold based. If e.g. 1 in 50 methods has high complexity, so be it.
# In strict, it may be valuable to have it low to find refactoring candidates.
CyclomaticComplexity:
  Max: 20 # strict: 6 - find candidates for refactoring