reek 2.1.0 → 2.2.0

data/docs/Duplicate-Method-Call.md

@@ -0,0 +1,49 @@
+# Duplicate Method Call
+
+## Introduction
+
+Duplication occurs when two fragments of code look nearly identical, or when two fragments of code have nearly identical effects at some conceptual level.
+`reek` implements a check for _Duplicate Method Call_.
+
+## Example
+
+Here's a very much simplified and contrived example. The following method will report a warning:
+
+```Ruby
+def double_thing()
+  @other.thing + @other.thing
+end
+```
+
+One quick approach to silence Reek would be to refactor the code thus:
+
+```Ruby
+def double_thing()
+  thing = @other.thing
+  thing + thing
+end
+```
+
+A slightly different approach would be to replace all calls of `double_thing` by calls to `@other.double_thing`:
+
+```Ruby
+class Other
+  def double_thing()
+    thing + thing
+  end
+end
+```
+
+The approach you take will depend on balancing other factors in your code.
+
+## Current support in reek
+
+`reek`'s Duplicate Method Call detector checks for repeated identical method calls within any one method definition. This is intended to complement the checks performed by tools such as [Flay](http://ruby.sadi.st/Flay.html) and [Simian](http://www.redhillconsulting.com.au/products/simian/).
+
+## Configuration
+
+Reek's Duplication detector currently offers the [Basic Smell Options](Basic-Smell-Options.md), plus:
+
+Option | Value | Effect
+-------|-------|-------
+`max_calls` |  integer | The maximum number of duplicate calls allowed within a method. Defaults to 1.

data/docs/Feature-Envy.md

@@ -0,0 +1,29 @@
+# Feature Envy
+
+## Introduction
+
+Feature Envy occurs when a code fragment references another object more often than it references itself, or when several clients do the same series of manipulations on a particular type of object.
+
+A simple example would be the following method, which "belongs" on the Item class and not on the Cart class:
+
+```Ruby
+class Cart
+  def price
+    @item.price + @item.tax
+  end
+end
+```
+
+`Feature Envy` reduces the code's ability to communicate intent: code that "belongs" on one class but which is located in another can be hard to find, and may upset the "System of Names" in the host class.
+
+`Feature Envy` also affects the design's flexibility: A code fragment that is in the wrong class creates couplings that may not be natural within the application's domain, and creates a loss of cohesion in the unwilling host class.
+
+`Feature Envy` often arises because it must manipulate other objects (usually its arguments) to get them into a useful form, and one force preventing them (the arguments) doing this themselves is that the common knowledge lives outside the arguments, or the arguments are of too basic a type to justify extending that type. Therefore there must be something which 'knows' about the contents or purposes of the arguments.  That thing would have to be more than just a basic type, because the basic types are either containers which don't know about their contents, or they are single objects which can't capture their relationship with their fellows of the same type. So, this thing with the extra knowledge should be reified into a class, and the utility method will most likely belong there.
+
+## Current Support in reek
+
+`Feature Envy` reports any method that refers to self less often than it refers to (ie. send messages to) some other object.
+
+## Configuration
+
+Feature Envy supports the [Basic Smell Options](Basic-Smell-Options.md).

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

@@ -0,0 +1,44 @@
+# How reek works internally
+
+**Using reek via bin/reek:**
+
+```
+            [bin/reek]
+                |
+                |
+                |
+          Application (cli/application.rb) +
+          Options (cli/options)
+                |
+                |
+                |
+      ReekCommand (cli/reek_command)
+      with Reporter (cli/report/report)
+          /     |    \
+         /      |     \
+        /       |      \
+    Source   Source   Source (source/source_code)
+    |           |          |
+    |           |          |
+    |           |          |
+ Examiner   Examiner  Examiner (examiner)
+                |
+                |
+                |
+    Examiner sets up a:
+      - SourceRepository (source/source_repository)
+      - a WarningCollector (core/warning_collector)
+
+    The Examiner then goes through each source:
+      - Initializing a SmellRepository (core/smell_repository)
+      - getting the AST from the source
+      - applying a TreeWalker(core/tree_walker) to process this syntax tree given the SmellRepository
+      - finally have that SmellRepository reporting back on the WarningCollector mentioned above
+                |
+                |
+                |
+    In the last step, the reporter from the ReekCommand:
+      - gathers all the warnings from the collectors of all Examiners (as you can see here https://github.com/troessner/reek/blob/master/lib/reek/cli/report/report.rb#L30)
+      - outputs them with whatever output format we have chose via the cli options
+```
+

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).