reek 2.1.0 → 2.2.0

data/docs/RSpec-matchers.md

@@ -0,0 +1,133 @@
+# RSpec matchers
+
+## Introduction
+
+`reek` offers matchers for RSpec you can easily include into your project.
+
+There are 3 matchers available:
+
+- `reek`
+- `reek_of`
+- `reek_only_of`
+
+## Quickstart
+
+Let's install the dependencies:
+
+```
+gem install reek
+gem install rspec
+```
+
+And then use it like that in your spec file:
+
+```Ruby
+require 'reek'
+require 'reek/spec'
+require 'rspec'
+
+RSpec.describe 'Reek Integration' do
+  it 'works with reek' do
+    smelly_class = 'class C; def m; end; end'
+    expect(smelly_class).not_to reek
+  end
+end
+```
+
+Running this via
+
+```
+rspec reek-integration-spec.rb 
+```
+
+would give you:
+
+```
+Failures:
+
+  1) Reek Integration works with reek
+     Failure/Error: expect(smelly_class).not_to reek
+       Expected no smells, but got:
+         C has no descriptive comment (IrresponsibleModule)
+         C has the name 'C' (UncommunicativeModuleName)
+         C#m has the name 'm' (UncommunicativeMethodName)
+     # ./reek-integration-spec.rb:8:in `block (2 levels) in <top (required)>'
+
+Finished in 0.00284 seconds (files took 0.28815 seconds to load)
+1 example, 1 failure
+
+Failed examples:
+
+rspec ./reek-integration-spec.rb:6 # Reek Integration works with reek
+```
+
+## The matchers explained
+
+### `reek`
+
+A very generic matcher that basically just tells you if something reeks, but not after what exactly.
+See the "Quickstart" example from above.
+
+### `reek_of`
+
+Checks the target source code for instances of "smell category"
+and returns true only if it can find one of them that matches.
+
+Remember that this includes our "smell types" as well. So it could be the
+"smell type" UtilityFunction, which is represented as a concrete class
+in reek but it could also be "Duplication" which is a "smell categgory".
+
+In theory you could pass many different types of input here:
+  - :UtilityFunction
+  - "UtilityFunction"
+  - UtilityFunction (this works in our specs because we tend to do "include Reek:Smells")
+  - Reek::Smells::UtilityFunction (the right way if you really want to pass a class)
+  - "Duplication" or :Duplication which is an abstract "smell category"
+
+It is recommended to pass this as a symbol like :UtilityFunction. However we don't
+enforce this.
+
+Additionally you can be more specific and pass in "smell_details" you
+want to check for as well e.g. "name" or "count" (see the examples below).
+The parameters you can check for are depending on the smell you are checking for.
+For instance "count" doesn't make sense everywhere whereas "name" does in most cases.
+If you pass in a parameter that doesn't exist (e.g. you make a typo like "namme") reek will
+raise an ArgumentError to give you a hint that you passed something that doesn't make
+much sense.
+
+So in a nutshell `reek_of` takes the following two arguments:
+
+- smell_category - The "smell category" or "smell_type" we check for.
+- smells_details - A hash containing "smell warning" parameters
+
+**Examples**
+
+ Without smell_details:
+
+```Ruby
+  reek_of(:FeatureEnvy)
+  reek_of(Reek::Smells::UtilityFunction)
+```
+
+With smell_details:
+
+```Ruby
+  reek_of(UncommunicativeParameterName, name: 'x2')
+  reek_of(DataClump, count: 3)
+```
+
+**Examples from a real spec**
+
+```Ruby
+  expect(src).to reek_of(Reek::Smells::DuplicateMethodCall, name: '@other.thing')
+```
+
+### reek_only_of
+
+See the documentaton for `reek_of`.
+
+**Notable differences to reek_of:**
+
+1.) `reek_of` doesn't mind if there are other smells of a different category. "reek_only_of" will fail in that case.
+
+2.) `reek_only_of` doesn't support the additional smell_details hash.

data/docs/Rake-Task.md

@@ -0,0 +1,58 @@
+# Rake Task
+
+## Introduction
+
+`reek`  provides a Rake task that runs `reek` on a set of source files. In its most simple form you just include something like that in your Rakefile:
+
+```Ruby
+require 'reek/rake/task'
+
+Reek::Rake::Task.new do |t|
+  t.fail_on_error = false
+end
+```
+
+In its most simple form, that's it.
+
+When you now run:
+
+```Bash
+rake -T
+```
+
+you should see
+
+```Bash
+rake reek  # Check for code smells
+```
+
+## Configuration via task
+
+An more sophisticated rake task that would make use of all available configuration options could look like this:
+
+```Ruby
+Reek::Rake::Task.new do |t|
+  t.name          = 'custom_rake' # Whatever name you want. Defaults to "reek".
+  t.config_file   = 'config/config.reek' # Defaults to nothing.
+  t.source_files  = 'vendor/**/*.rb' # Glob pattern to match source files. Defaults to lib/**/*.rb
+  t.reek_opts     = '-U'  # Defaults to ''. You can pass all the options here in that are shown by "reek -h"
+  t.fail_on_error = false # Defaults to true
+  t.verbose       = true  # Defaults to false
+end
+```
+
+## Configuration via environment variables
+
+You can overwrite the following attributes by environment variables:
+
+- "reek_opts" by using REEK_OPTS
+- "config_file" by using REEK_CFG
+- "source_files" by using REEK_SRC
+
+An example rake call using environment variables could look like this:
+
+```Bash
+REEK_CFG="config/custom.reek" REEK_OPTS="-s" rake reek
+```
+
+See also: [Reek-Driven-Development](Reek-Driven-Development.md)

data/docs/Reek-Driven-Development.md

@@ -0,0 +1,45 @@
+# Reek Driven Development
+
+## rake
+
+One way to drive quality into your code from the very beginning of a project is to run `reek` as a part of your testing process. For example, you could do that by adding a [Rake Task](Rake-Task.md) to your rakefile, which will make it easy to run `reek` on all your source files whenever you need to.
+
+```Ruby
+require 'reek/rake/task'
+
+Reek::Rake::Task.new do |t|
+  t.fail_on_error = true
+  t.verbose = false
+  t.source_files = 'lib/**/*.rb'
+end
+```
+
+Now the command `reek` will run `reek` on your source code (and in this case, it fails if it finds any smells). For more detailed information about `reek`'s integration with Rake, see [Rake Task](Rake-Task.md) in this wiki.
+
+## reek/spec
+
+But there's another way; a much more effective "Reek-driven" approach: add `reek` expectations directly into your Rspec specs. Here's an example taken directly from `reek`'s own source code:
+
+```Ruby
+it 'contains no code smells' do
+  Dir['lib/**/*.rb'].should_not reek
+end
+```
+
+By requiring "reek/spec":http://reek.rubyforge.org/rdoc/classes/Reek/Spec.html you gain access to the `reek` matcher, which returns true if and only if `reek` finds smells in your code. And if the test fails, the matcher produces an error message that includes details of all the smells it found.
+
+Note: if you're on ruby 1.9  and RSpec2 you should include Reek::Spec in the configuration block like so,
+
+```Ruby
+RSpec.configure do |c|
+  c.include(Reek::Spec)
+end
+```
+
+## assert
+
+If you're not yet into BDD with Rspec, you can still gain the benefits of Reek-driven development using assertions:
+
+```Ruby
+assert !Dir['lib/**/*.rb'].to_source.smelly?
+```

data/docs/Repeated-Conditional.md

@@ -0,0 +1,44 @@
+# Repeated Conditional
+
+## Introduction
+
+`Repeated Conditional` is a special case of [Simulated Polymorphism](Simulated-Polymorphism.md). Basically it means you are checking the same value throughout a single class and take decisions based on this.
+
+## Example
+
+Given
+
+```Ruby
+class RepeatedConditionals
+  attr_accessor :switch
+
+  def repeat_1
+    puts "Repeat 1!" if switch
+  end
+
+  def repeat_2
+    puts "Repeat 2!" if switch
+  end
+
+  def repeat_3
+    puts "Repeat 3!" if switch
+  end
+end
+```
+
+`reek` would emit the following warning:
+
+```
+test.rb -- 4 warnings:
+  [5, 9, 13]:RepeatedConditionals tests switch at least 3 times (RepeatedConditional)
+```
+
+If you get this warning then you are probably not using the right abstraction or even more probable, missing an additional abstraction.
+
+## Configuration
+
+`reek`'s `Repeated Conditional` detector offers the [Basic Smell Options](Basic-Smell-Options.md), plus:
+
+| Option         | Value       | Effect  |
+| ---------------|-------------|---------|
+| `max_ifs` |  integer | The maximum number of identical conditional tests permitted before Reek raises a warning. Defaults to 2. |

data/docs/Simulated-Polymorphism.md

@@ -0,0 +1,16 @@
+# Simulated Polymorphism
+
+## Introduction
+
+Simulated Polymorphism occurs when
+
+* code uses a case statement (especially on a type field);
+* or code has several if statements in a row (especially if they're comparing against the same value);
+* or code uses instance_of?, kind_of?, is_a?, or === to decide what type it's working with;
+* or multiple conditionals in different places test the same value.
+
+Conditional code is hard to read and understand, because the reader must hold more state in his head. When the same value is tested in multiple places throughout an application, any change to the set of possible values will require many methods and classes to change. Tests for the type of an object may indicate that the abstraction represented by that type is not completely defined (or understood).
+
+## Current Support in reek
+
+`reek` checks for [Repeated Conditional](Repeated-Conditional.md)  and for [Nil Check](Nil-Check.md).

data/docs/Smell-Suppression.md

@@ -0,0 +1,32 @@
+## Introduction
+
+In some cases, it might be necessary to suppress one or more of `reek`'s smell warnings for a particular method or class. 
+
+Possible reasons for this could be:
+
+* The code is outside of your control and you can't fix it
+* `reek` is not the police. You might have legit reasons why your source code is good as it is.
+
+## How to disable smell detection
+
+First and foremost, there are the [Basic Smell Options](Basic-Smell-Options.md) you can use.
+
+Besides from that, you can use special comments, like so:
+
+```ruby
+# This method smells of :reek:NestedIterators
+def smelly_method foo
+  foo.each {|bar| bar.each {|baz| baz.qux}}
+end
+```
+
+The method `smelly_method` will not be reported. The general pattern is to put the string ':reek:', followed by the smell class, in a comment before the method or class.
+
+It is also possible to specify options for a particular smell detector, like so:
+
+```ruby
+# :reek:LongParameterList: { max_params: 4 }
+def many_parameters_it_has foo, bar, baz, qux
+  # ...
+end
+```

data/docs/Too-Many-Instance-Variables.md

@@ -0,0 +1,43 @@
+## Introduction
+
+`Too Many Instance Variables` is a special case of `LargeClass`. 
+
+## Example
+
+Given this configuration
+
+```yaml
+TooManyInstanceVariables:
+  max_instance_variables: 3
+```
+
+and this code:
+
+```Ruby
+class TooManyInstanceVariables
+  def initialize
+    @arg_1 = :dummy
+    @arg_2 = :dummy
+    @arg_3 = :dummy
+    @arg_4 = :dummy
+  end
+end
+```
+
+`reek` would emit the following warning:
+
+```
+test.rb -- 5 warnings:
+  [1]:TooManyInstanceVariables has at least 4 instance variables (TooManyInstanceVariables)
+```
+## Current Support in `reek`
+
+`reek` only counts the instance variables you use explicitly like in the example above. Class macros like `attr_accessor` are disregarded.
+
+## Configuration
+
+`reek`'s `Too Many Instance Variables` detector offers the [Basic Smell Options](Basic-Smell-Options.md), plus:
+
+| Option         | Value       | Effect  |
+| ---------------|-------------|---------|
+| max_instance_variables     | integer | The maximum number of instance variables that are permitted. Defaults to 9 |

data/docs/Too-Many-Methods.md

@@ -0,0 +1,55 @@
+## Introduction
+
+`Too Many Methods` is a special case of `LargeClass`. 
+
+## Example
+
+Given this configuration
+
+```yaml
+TooManyMethods:
+  max_methods: 3
+```
+
+and this code:
+
+```Ruby
+class TooManyMethods
+  def one; end
+  def two; end
+  def three; end
+  def four; end
+end
+```
+
+`reek` would emit the following warning:
+
+```
+test.rb -- 1 warning:
+  [1]:TooManyMethods has at least 4 methods (TooManyMethods)
+```
+## Current Support in `reek`
+
+`reek` counts all the methods it can find in a `class` - instance *and* class methods. So given `max_methods` from above is 4, this:
+
+```Ruby
+class TooManyMethods
+  class << self
+    def one; end
+    def two; end
+  end
+
+  def three; end
+  def four; end
+end
+```
+
+would cause reek to emit the same warning as in the example above.
+
+## Configuration
+
+`reek`'s `Too Many Methods` detector offers the [Basic Smell Options](Basic-Smell-Options.md), plus:
+
+| Option         | Value       | Effect  |
+| ---------------|-------------|---------|
+| max_methods     | integer | The maximum number of methods that are permitted. Defaults to 25 |

data/docs/Too-Many-Statements.md

@@ -0,0 +1,50 @@
+# Too Many Statements
+
+## Introduction
+
+A method with `Too Many Statements` is any method that has a large number of lines.
+
+## Current Support in Reek
+
+`Too Many Statements` warns about any method that has more than 5 statements. `reek`'s smell detector for `Too Many Statements` counts +1 for every simple statement in a method and +1 for every statement within a control structure (`if`, `else`, `case`, `when`, `for`, `while`, `until`, `begin`, `rescue`) but it doesn't count the control structure itself.
+
+So the following method would score +6 in Reek's statement-counting algorithm:
+
+```Ruby
+def parse(arg, argv, &error)
+  if !(val = arg) and (argv.empty? or /\A-/ =~ (val = argv[0]))
+    return nil, block, nil                                         # +1
+  end
+  opt = (val = parse_arg(val, &error))[1]                          # +2
+  val = conv_arg(*val)                                             # +3
+  if opt and !arg
+    argv.shift                                                     # +4
+  else
+    val[0] = nil                                                   # +5
+  end
+  val                                                              # +6
+end
+```
+
+(You might argue that the two assigments within the first @if@ should count as statements, and that perhaps the nested assignment should count as +2.)
+
+## Configuration
+
+`reek`'s `Too Many Statements` detector supports the [Basic Smell Options](Basic-Smell-Options.md), plus:
+
+| Option         | Value       | Effect  |
+| ---------------|-------------|---------|
+| `max_statements` |  integer | The maximum number of statements allowed in a method before a warning is issued. Defaults to 5. |
+
+`Too Many Statements`'s default configuration is:
+
+```yaml
+---
+TooManyStatements:
+  enabled: true
+  exclude:
+  - initialize
+  max_statements: 5
+```
+
+By default, `initialize` is not checked for length; any class's constructor can be as long as necessary.