reek 2.0.4 → 3.0.0

data/docs/How-reek-works-internally.md

@@ -0,0 +1,114 @@
+# How reek works internally
+
+
+## The big picture
+
+```
+["class C; end" | reek]            [reek lib/*.rb]                             [expect(files).not_to reek_of(:LargeClass)]
+             \                            |                                                          |
+              \                           |                                                          |
+               \                          |                                                          |
+                \             creates a   |                                                          |
+                 \                        |                                                          |
+                  \                       |                                                          |
+                   \                      |                                                          |
+                    \                     |                                                          |
+                     \---------- Application (cli/application.rb) +                                  |
+                                    Options (cli/options)                                            |
+                                          |                                                          |
+                                          |                                                          |
+                                          |                                                          |
+                                          |                                                          |
+                              creates a   |                                                          |
+                                          |                                                          |
+                                          |                                                          |
+                                          |                                                          |
+                                          |                                                          |
+                                ReekCommand (cli/reek_command)                                       |
+                                * uses a reporter (report/report)                                |
+                                * uses a SourceLocator (source/source_locator)                       |
+                                /         |         \                                                |
+                               /          |          \                                               |
+                              /           |           \                                              |
+                        Source          Source      Source (source/source_code)                      |
+                          |               |            |                                             |
+                          |               |            |                                             |
+                          |               |            |                                             |
+                      Examiner            |         Examiner                                         |
+                                          |                                                          |
+                                          |                                                          |
+                                      Examiner (core/examiner)  --------------------------------------
+                                  * generates the AST out of the given source
+                                  * adorns the generated AST via a TreeDresser (core/tree_dresser)
+                                  * initializes a SmellRepository with all relevant smells (smells/smell_repository)
+                                  * initializes a WarningCollector (cli/warning_collector)
+                                  * runs all corresponding smell detectors via a Treewalker (core/tree_walker) for the SmellRepository above
+                                  /       |       \
+                                 /        |        \
+                                /         |         \
+                    UtilityFunction   FeatureEnvy   TooManyMethods
+                                \         |         /
+                                 \        |        /
+                                  \       |       /
+                                   WarningCollector
+                                          |
+                                          |
+                                          |
+                                    Application output
+
+## A closer look at how an Examiner works
+
+The core foundation of reek and its API is the Examiner.
+As you can see above, the Examiner is run for every source it gets passed and then runs the configured SmellDetectors.
+The overall workflow is like this:
+
+        Examiner
+            |
+            |
+            |
+        Initialize SmellRepository only with eligible smells
+            |
+            |
+            |
+    Generate the AST out of the given source using SourceCode#syntax_tree, which works like this:
+
+      - We generate a "rough" AST using the "parser" gem
+      - We then obtain the comments from the source code separately
+      - We pass this unprocessed AST and the comment_map to TreeDresser#dress which
+        returns an instance of Reek::AST::SexpNode with type-dependent SexpExtensions mixed in.
+
+    An example should make this more palpable.
+    Given:
+
+      class C
+        def m
+          puts 'nada'
+        end
+      end
+
+    The AST generated by the parser gem (consisting of Parser::AST::Node) looks like this:
+
+       (class
+         (const nil :C)
+          nil
+         (def :m
+           (args)
+           (send nil :puts
+             (str "nada"))))
+
+    TreeDresser#dress would transform this into a very similar tree, but this time not consisting
+    of Parser::AST::Node but of Reek::AST::SexpNode and with node-dependent SexpExtensions
+    mixed in (noted in []):
+
+       (class                 [AST::SexpExtensions::ClassNode, AST::SexpExtensions::ModuleNode]
+         (const nil :C)       [AST::SexpExtensions::ConstNode]
+          nil
+         (def :m              [AST::SexpExtensions::DefNode, AST::SexpExtensions::MethodNodeBase]
+           (args)             [AST::SexpExtensions::ArgsNode]
+           (send nil :puts    [AST::SexpExtensions::SendNode]
+             (str "nada"))))
+            |
+            |
+            |
+      A TreeWalker then traverses this now adorned tree again and
+      runs all SmellDetectors from the SmellRepository above

data/docs/Irresponsible-Module.md

@@ -0,0 +1,39 @@
+# Irresponsible Module
+
+## Introduction
+
+Classes and modules are the units of reuse and release. It is therefore considered good practice to annotate every class and module with a brief comment outlining its responsibilities.
+
+## Example
+
+Given
+
+```Ruby
+class Dummy
+  # Do things...
+end
+```
+
+`reek` would emit the following warning:
+
+```
+test.rb -- 1 warning:
+  [1]:Dummy has no descriptive comment (IrresponsibleModule)
+```
+
+Fixing this is simple - just an explaining comment:
+
+```Ruby
+# The Dummy class is responsible for ...
+class Dummy
+  # Do things...
+end
+```
+
+## Current Support in reek
+
+`Irresponsible Module` currently checks classes, but not modules.
+
+## Configuration
+
+`Irresponsible Module` supports only the [Basic Smell Options](Basic-Smell-Options.md).

data/docs/Large-Class.md

@@ -0,0 +1,20 @@
+# Large Class
+
+## Introduction
+
+A `Large Class` is a class or module that has a large number of instance variables, methods or lines of code in any one piece of its specification. (That is, this smell relates to pieces of the class's specification, not to the size of the corresponding instance of `Class`.)
+
+## Current Support in Reek
+
+`Large Class` reports classes having more than a configurable number of methods or instance variables. The method count includes public, protected and private methods, and excludes methods inherited from superclasses or included modules.
+
+##  Configuration
+
+`reek`'s Large Class detector supports the [Basic Smell Options](Basic-Smell-Options.md), plus:
+
+| Option         | Value       | Effect  |
+| ---------------|-------------|---------|
+| max_methods |  integer | The maximum number of methods allowed in a class before a warning is issued. Defaults to 25. |
+| max_instance_variables |  integer | The maximum number of instance variables allowed in a class before a warning is issued. Defaults to 9. |
+
+The `Large Class` detector is enabled whenever `reek` is asked to check an instance of `Class` or `Module`.

data/docs/Long-Parameter-List.md

@@ -0,0 +1,38 @@
+# Long Parameter List
+
+## Introduction
+
+A `Long Parameter List` occurs when a method has a lot of parameters.
+
+## Example
+
+Given
+
+```Ruby
+class Dummy
+  def long_list(foo,bar,baz,fling,flung)
+    puts foo,bar,baz,fling,flung
+  end
+end
+```
+
+`reek` would report the following warning:
+
+```
+test.rb -- 1 warning:
+  [2]:Dummy#long_list has 5 parameters (LongParameterList)
+```
+
+A common solution to this problem would be the introduction of parameter objects.
+
+## Current Support in Reek
+
+`Long Parameter List` reports any method or block with more than 3 parameters.
+
+## Configuration
+
+Reek's Long Parameter List detector supports the [Basic Smell Options](Basic-Smell-Options.md), plus:
+
+| Option         | Value       | Effect  |
+| ---------------|-------------|---------|
+| max_params |  integer | The maximum number of parameters allowed in a method or block before a warning is issued. Defaults to 3. |

data/docs/Long-Yield-List.md

@@ -0,0 +1,36 @@
+# Long Yield List
+
+## Introduction
+
+A _Long Yield List_ occurs when a method yields a lot of arguments to the block it gets passed.
+
+## Example
+
+```Ruby
+class Dummy
+  def yields_a_lot(foo,bar,baz,fling,flung)
+    yield foo,bar,baz,fling,flung
+  end
+end
+```
+
+`reek` would report the following warning:
+
+```
+test.rb -- 1 warning:
+  [4]:Dummy#yields_a_lot yields 5 parameters (LongYieldList)
+```
+
+A common solution to this problem would be the introduction of parameter objects.
+
+## Current Support in Reek
+
+Currently Long Parameter List reports any method or block with more than 3 parameters.
+
+## Configuration
+
+Reek's Long Parameter List detector supports the [Basic Smell Options](Basic-Smell-Options.md), plus:
+
+| Option         | Value       | Effect  |
+| ---------------|-------------|---------|
+| max_params |  integer | The maximum number of parameters allowed in a method or block before a warning is issued. Defaults to 3. |

data/docs/Module-Initialize.md

@@ -0,0 +1,62 @@
+# Module Initialize
+
+## Introduction
+
+A module is usually a mixin, so when an `#initialize` method is present it is
+hard to tell initialization order and parameters so having `#initialize`
+in a module is usually a bad idea.
+
+## Example
+
+The `Foo` module below contains a method `initialize`. Although class `B` inherits from `A`, the inclusion of `Foo` stops `A#initialize` from being called.
+
+```Ruby
+class A
+  def initialize(a)
+    @a = a
+  end
+end
+
+module Foo
+  def initialize(foo)
+    @foo = foo
+  end
+end
+
+class B < A
+  include Foo
+
+  def initialize(b)
+    super('bar')
+    @b = b
+  end
+end
+```
+
+A simple solution is to rename `Foo#initialize` and call that method by name:
+
+```Ruby
+module Foo
+  def setup_foo_module(foo)
+    @foo = foo
+  end
+end
+
+class B < A
+  include Foo
+
+  def initialize(b)
+    super 'bar'
+    setup_foo_module('foo')
+    @b = b
+  end
+end
+```
+
+## Current Support in reek
+
+`reek` warns about module initialize when an instance method named `initialize` is present in a module.
+
+## Configuration
+
+Module Initialize supports the [Basic Smell Options](Basic-Smell-Options.md).

data/docs/Nested-Iterators.md

@@ -0,0 +1,38 @@
+# Nested Iterators
+
+## Introduction
+
+A `Nested Iterator` occurs when a block contains another block.
+
+## Example
+
+Given
+
+```Ruby
+class Duck
+  class << self
+    def duck_names
+      %i!tick trick track!.each do |surname|
+        %i!duck!.each do |last_name|
+          puts "full name is #{surname} #{last_name}"
+        end
+      end
+    end
+  end
+end
+```
+
+`reek` would report the following warning:
+
+```
+test.rb -- 1 warning:
+  [5]:Duck#duck_names contains iterators nested 2 deep (NestedIterators)
+```
+
+## Current Support in Reek
+
+Nested Iterators reports failing methods only once.
+
+## Configuration
+
+`Nested Iterators` offers the [Basic Smell Options](Basic-Smell-Options.md).

data/docs/Nil-Check.md

@@ -0,0 +1,39 @@
+# Nil Check
+
+## Introduction
+
+A `NilCheck` is a type check. Failures of `NilCheck` violate the ["tell, don't ask"](http://robots.thoughtbot.com/tell-dont-ask) principle.
+Additionally to that, type checks often mask bigger problems in your source code like not using OOP and / or polymorphism when you should.
+
+## Example
+
+Given
+
+```Ruby
+class Klass
+  def nil_checker(argument)
+    if argument.nil?
+      puts "argument isn't nil!"
+    end
+  end
+end
+```
+
+`reek` would emit the following warning:
+
+```
+test.rb -- 1 warning:
+  [3]:Klass#nil_checker performs a nil-check. (NilCheck)
+```
+
+##  Current Support in Reek
+
+`NilCheck` reports use of 
+
+* <code>.nil?</code> method
+* <code>==</code> and <code>===</code> operators when checking vs. <code>nil</code>
+* case statements that use syntax like <code>when nil</code>
+
+## Configuration
+
+`Nil Check` offers the [Basic Smell Options](Basic-Smell-Options.md).

data/docs/Prima-Donna-Method.md

@@ -0,0 +1,53 @@
+# Prima Donna Method
+
+## Introduction
+
+A candidate method for the `Prima Donna Method` smell are methods whose names end with an exclamation mark.
+
+An exclamation mark in method names means (the explanation below is taken from [here](http://dablog.rubypal.com/2007/8/15/bang-methods-or-danger-will-rubyist) ):
+
+>>
+The ! in method names that end with ! means, “This method is dangerous”—or, more precisely, this method is the “dangerous” version of an otherwise equivalent method, with the same name minus the !. “Danger” is relative; the ! doesn’t mean anything at all unless the method name it’s in corresponds to a similar but bang-less method name.
+So, for example, gsub! is the dangerous version of gsub. exit! is the dangerous version of exit. flatten! is the dangerous version of flatten. And so forth.
+
+Such a method is called `Prima Donna Method` if and only if her non-bang version does not exist and this method is reported as a smell.
+
+## Example
+
+Given
+
+```Ruby
+class C
+  def foo; end
+  def foo!; end
+  def bar!; end
+end
+```
+
+`reek` would report `bar!` as `prima donna method` smell but not `foo!`.
+
+`reek` reports this smell only in a class context, not in a module context in order to allow perfectly legit code like this:
+
+
+```Ruby
+class Parent
+  def foo; end
+end
+
+module Dangerous
+  def foo!; end
+end
+
+class Son < Parent
+  include Dangerous
+end
+
+class Daughter < Parent
+end
+```
+
+In this example, `reek` would not report the `prima donna method` smell for the method `foo` of the `Dangerous` module.
+
+## Configuration
+
+`Prima Donna Method` offers the [Basic Smell Options](Basic-Smell-Options.md).

data/docs/RSpec-matchers.md

@@ -0,0 +1,137 @@
+# 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,37 @@
+# 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.
+
+## 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?
+```