reek 2.0.4 → 3.0.0

data/docs/API.md

@@ -0,0 +1,79 @@
+# Using `reek` inside your Ruby application
+
+`reek` can be used inside another Ruby project.
+
+```bash
+gem install reek
+```
+
+## Using a reporter
+
+You can use reek inside your Ruby file `check_dirty.rb`
+
+```ruby
+require 'reek'
+
+source = <<-END
+  class Dirty
+    # This method smells of :reek:NestedIterators but ignores them
+    def awful(x, y, offset = 0, log = false)
+      puts @screen.title
+      @screen = widgets.map { |w| w.each { |key| key += 3 * x } }
+      puts @screen.contents
+      fail
+    end
+  end
+END
+
+reporter = Reek::Report::TextReport.new
+examiner = Reek::Examiner.new(source)
+reporter.add_examiner examiner
+reporter.show
+```
+
+This will show the list of errors in variable `source`.
+
+`Reek::Examiner.new` can take `source` as `String`, `File` or `IO`.
+
+```
+# Examine a file object
+reporter.add_examiner Reek::Examiner.new(File.new('dirty.rb'))
+```
+
+Also, besides normal text output, `reek` can generate output in YAML,
+JSON, HTML and XML by using the following Report types:
+
+```
+TextReport
+YAMLReport
+JSONReport
+HTMLReport
+XMLReport
+```
+
+## Accessing the smell warnings directly
+
+You can also access the smells detected by an examiner directly:
+
+```ruby
+require 'reek'
+
+source = <<-END
+  class Dirty
+    # This method smells of :reek:NestedIterators but ignores them
+    def awful(x, y, offset = 0, log = false)
+      puts @screen.title
+      @screen = widgets.map { |w| w.each { |key| key += 3 * x } }
+      puts @screen.contents
+      fail
+    end
+  end
+END
+
+examiner = Reek::Examiner.new(source)
+examiner.smells.each do |smell|
+  puts smell.message
+end
+```
+
+`Examiner#smells` returns a list of `SmellWarning` objects.

data/docs/Attribute.md

@@ -0,0 +1,43 @@
+# Attribute
+
+## Introduction
+
+A class that publishes a getter or setter for an instance variable invites client classes to become too intimate with its inner workings, and in particular with its representation of state.
+
+## Example
+
+Given:
+
+```Ruby
+class Klass
+  attr_accessor :dummy
+end
+```
+
+`reek` would emit the following warning:
+
+```
+reek test.rb
+
+test.rb -- 1 warning:
+  [2]:Klass declares the attribute dummy (Attribute)
+```
+
+## Support in Reek
+
+Right now this smell is disabled by default since it is highly subjective.
+
+When this detector is enabled it raises a warning for every `attr`, `attr_reader`, `attr_writer` and `attr_accessor` -- including those that are private.
+
+## Configuration
+
+If you want to enable it you can do so by placing
+
+```yaml
+Attribute:
+  enabled: true
+```
+
+in your reek configuration file.
+
+`Attribute` supports only the [Basic Smell Options](Basic-Smell-Options.md).

data/docs/Basic-Smell-Options.md

@@ -0,0 +1,44 @@
+# Basic Smell Options
+
+## Introduction
+
+Every smell detector in Reek offers at least the following configuration options:
+
+| Option         | Value       | Effect  |
+| ---------------|-------------|---------|
+| `enabled` |  Boolean | Determines whether the smell detector is active. Defaults to `true` |
+| `exclude` | an array of strings or regular expressions | Ignores any context whose full description (see <strong>%c</strong> in [Command-Line Options](Command-Line-Options.md)) matches any element of this array. |
+
+The file `config/defaults.reek` (shipped with the Reek gem) lists any default exclusions for each smell.
+
+## Examples
+
+<u>An easy one:</u>
+
+To stop Reek reporting smells in any method called `write` you might create a configuration file containing this:
+
+```yaml
+ControlCouple: 
+  exclude:
+  - write
+```
+
+Or a little more sophisticated using a ruby regex like this:
+
+```yaml
+ControlCouple: 
+  exclude:
+  - !ruby/regexp /write/
+```
+
+<u>A more sophisticated one:</u>
+
+```yaml
+FeatureEnvy:
+  exclude:
+    - "MyModel#do_things"
+    - "MyHelper"
+    - "ApplicationController#respond"
+```
+
+This would not report FeatureEnvy for the instance method `MyModel#do_things`, the whole module `MyHelper` and the `respond` instance method of `ApplicationController`

data/docs/Boolean-Parameter.md

@@ -0,0 +1,52 @@
+# Boolean Parameter
+
+## Introduction
+
+`Boolean Parameter` is a special case of [Control Couple](Control-Couple.md), where a method parameter is defaulted
+to true or false. A _Boolean Parameter_ effectively permits a method's caller
+to decide which execution path to take. This is a case of bad cohesion. You're creating a dependency between methods that is not really necessary, thus increasing coupling.
+
+## Example
+
+Given
+
+```Ruby
+class Dummy
+  def hit_the_switch(switch = true)
+    if switch
+      puts 'Hitting the switch'
+      # do other things...
+    else
+      puts 'Not hitting the switch'
+      # do other things...
+    end
+  end
+end
+```
+
+`reek` would emit the following warning:
+
+```
+test.rb -- 3 warnings:
+  [1]:Dummy#hit_the_switch has boolean parameter 'switch' (BooleanParameter)
+  [2]:Dummy#hit_the_switch is controlled by argument switch (ControlParameter)
+```
+
+Note that both smells are reported, `Boolean Parameter` and `Control Parameter`.
+
+## Getting rid of the smell
+
+This is highly dependant on your exact architecture, but looking at the example above what you could do is:
+
+* Move everything in the `if` branch into a separate method
+* Move everything in the `else` branch into a separate method
+* Get rid of the `hit_the_switch` method alltogether
+* Make the decision what method to call in the initial caller of `hit_the_switch`
+
+## Current support in Reek
+
+Reek can only detect a Boolean parameter when it has a default initializer like in the example above.
+
+## Configuration
+
+`Boolean Parameter` supports the [Basic Smell Options](Basic-Smell-Options.md).

data/docs/Class-Variable.md

@@ -0,0 +1,40 @@
+# Class Variable
+
+## Introduction
+
+Class variables form part of the global runtime state, and as such make it easy for one part of the system to accidentally or inadvertently depend on another part of the system. So the system becomes more prone to problems where changing something over here breaks something over there. In particular, class variables can make it hard to set up tests (because the context of the test includes all global state).
+
+For a detailed explanation, check out [this article](http://4thmouse.com/index.php/2011/03/20/why-class-variables-in-ruby-are-a-bad-idea/)
+
+## Example
+
+Given
+
+```Ruby
+class Dummy
+  @@class_variable = :whatever
+end
+```
+
+`reek` would emit the following warning:
+
+```
+reek test.rb 
+
+test.rb -- 1 warning:
+  [2]:Dummy declares the class variable @@class_variable (ClassVariable)
+```
+
+## Getting rid of the smell
+
+You can use class-instance variable to mitigate the problem (as also suggested in the linked article above):
+
+```Ruby
+class Dummy
+  @class_variable = :whatever
+end
+```
+
+##  Configuration
+
+`Class Variable` supports the [Basic Smell Options](Basic-Smell-Options.md).

data/docs/Code-Smells.md

@@ -0,0 +1,34 @@
+# Code Smells
+
+Smells are indicators of where your code might be hard to read, maintain or evolve, rather than things that are specifically _wrong_. Naturally this means that Reek is looking towards your code's future (and that can make its reports seem somewhat subjective, of course).
+
+Reek currently includes checks for the following smells:
+
+* [Attribute](Attribute.md) (disabled by default)
+* [Class Variable](Class-Variable.md)
+* [Control Couple](Control-Couple.md), including
+  * [Boolean Parameter](Boolean-Parameter.md)
+  * [Control Parameter](Control-Parameter.md)
+* [Data Clump](Data-Clump.md)
+* [Duplicate Method Call](Duplicate-Method-Call.md)
+* [Irresponsible Module](Irresponsible-Module.md)
+* [Large Class](Large-Class.md), including
+  * [Too Many Instance Variables](Too-Many-Instance-Variables.md)
+  * [Too Many Methods](Too-Many-Methods.md)
+* [Long Parameter List](Long-Parameter-List.md), and its special case [Long Yield List](Long-Yield-List.md)
+* Low Cohesion, including
+  * [Feature Envy](Feature-Envy.md)
+  * [Utility Function](Utility-Function.md)
+* [Module Initialize](Module-Initialize.md)
+* [Nested Iterators](Nested-Iterators.md)
+* [Prima-Donna-Method](Prima-Donna-Method.md)
+* [Simulated Polymorphism](Simulated-Polymorphism.md), including
+  * [Nil Check](Nil-Check.md)
+  * [Repeated Conditional](Repeated-Conditional.md)
+* [Too Many Statements](Too-Many-Statements.md)
+* [Uncommunicative Name](Uncommunicative-Name.md), including
+  * [Uncommunicative Method Name](Uncommunicative-Method-Name.md)
+  * [Uncommunicative Module Name](Uncommunicative-Module-Name.md)
+  * [Uncommunicative Parameter Name](Uncommunicative-Parameter-Name.md)
+  * [Uncommunicative Variable Name](Uncommunicative-Variable-Name.md)
+* [Unused Parameters](Unused-Parameters.md)

data/docs/Command-Line-Options.md

@@ -0,0 +1,84 @@
+# Command Line Options
+
+## Introduction
+
+reek follows standard Unix convention for passing arguments.
+
+Check out
+
+```Bash
+reek -h
+```
+
+for details.
+
+## Telling Reek Which Code to Check
+
+Probably the most standard use case would be to check all ruby files in the lib directory:
+
+```Bash
+reek lib/*.rb
+```
+
+In general, if any command-line argument is a directory, Reek searches that directory and all sub-directories for Ruby source files. Thus
+
+```Bash
+reek lib
+```
+
+would be equivalent to 
+
+```Bash
+reek lib/**/*.rb
+```
+
+Occasionally you may want to quickly check a code snippet without going to the trouble of creating a file to hold it. You can pass the snippet directly to Reek's standard input:
+
+```Bash
+echo "def x() true end" | reek
+```
+
+## Output options
+
+### Output smell's line number
+
+By passing in a "-n" flag to the _reek_ command, the output will suppress the line numbers:
+
+```Bash
+$ reek -n mess.rb
+```
+
+```
+mess.rb -- 2 warnings:
+  x doesn't depend on instance state (UtilityFunction)
+  x has the name 'x' (UncommunicativeMethodName)
+```
+
+Otherwise line numbers will be shown as default at the beginning of each warning in square brackets:
+
+```Bash
+$ reek mess.rb
+```
+
+```
+mess.rb -- 2 warnings:
+  [2]:x doesn't depend on instance state (UtilityFunction)
+  [2]:x has the name 'x' (UncommunicativeMethodName)
+```
+
+### Enable the ultra-verbose mode
+
+_reek_ has a ultra-verbose mode which you might find helpful as a beginner. "ultra-verbose" just means that behind each warning a helpful link will be displayed which leads directly to the corresponding _reek_ wiki page.
+This mode can be enabled via the "-U" or "--ultra-verbose" flag.
+
+So for instance, if your test file would smell of _ClassVariable_, this is what the _reek_ output would look like:
+
+```Bash
+reek -U test.rb 
+```
+```
+test.rb -- 1 warning:
+  [2]:Dummy declares the class variable @@class_variable (ClassVariable) [https://github.com/troessner/reek/wiki/Class-Variable]
+```
+
+Note the link at the end.

data/docs/Configuration-Files.md

@@ -0,0 +1,49 @@
+# Configuration Files
+
+## Configuration loading
+
+Configuring `reek` via configuration file is by far the most powerful way.
+
+There are 3 ways of passing `reek` a configuration file:
+
+1. Using the cli "-c" switch (see [Command Line Options](Command-Line-Options.md))
+2. Having a file ending with .reek either in your current working directory or in a parent directory (more on that later)
+3. Having a file ending with .reek in your HOME directory
+
+The order in which `reek` tries to find such a configuration file is exactly like above: First `reek` checks if we have given it a configuration file explicitly via CLI. Then it checks the current working directory for a file and if it can't find one, it traverses up the directories until it hits the root directory. And lastly, it checks your HOME directory.
+
+As soon as `reek` detects a configuration file it stops searching immediately, meaning that from `reek`'s point of view there exists one configuration file and one configuration only regardless of how many ".reek" files you might have on your filesystem.
+
+## Configuration options for smells
+
+The first thing you probably want to check out are the [Basic Smell Options](Basic-Smell-Options.md) which are supported by every smell type.
+Certain smell types offer a configuration that goes beyond that of the basic smell options - for instance [Data Clump](Data-Clump.md).
+All options that go beyond the [Basic Smell Options](Basic-Smell-Options.md) should be documented in the corresponding smell type wiki page but if you want to get a quick and full overview over all possible configurations you can always check out [the default.reek file in this repository](https://github.com/troessner/reek/blob/master/config/defaults.reek).
+
+Here's an excerpt of a `reek` configuration file from a commercial project:
+
+```yaml
+---
+IrresponsibleModule:
+  enabled: false
+NestedIterators:
+  exclude:
+    - "ActiveModelErrorAdder#self.run" # should be refactored
+    - "BookingRequests::Transfer#remote_validation"
+    - "BookingRequestsController#vehicle_options" # respond_to block
+    - "Content::Base#self.expose_fields" # unavoidable due to metaprogramming
+DataClump:
+  max_copies: 3
+  min_clump_size: 3
+```
+
+## Excluding directories from scans
+
+You can exclude whole directories from scans using `exclude_paths` in your configuration file:
+
+```yaml
+---
+exclude_paths:
+  - app/views
+  - app/controllers
+```

data/docs/Control-Couple.md

@@ -0,0 +1,22 @@
+# Control Couple
+
+## Introduction
+
+Control coupling occurs when a method or block checks the value of a parameter in order to decide which execution path to take. The offending parameter is often called a `Control Couple`.
+
+Control Coupling is a kind of duplication, because the calling method already knows which path should be taken.
+
+Control Coupling reduces the code's flexibility by creating a dependency between the caller and callee: any change to the possible values of the controlling parameter must be reflected on both sides of the call. A `Control Couple` also reveals a loss of simplicity: the called method probably has more than one responsibility, because it includes at least two different code paths.
+
+You can find a good write-up regarding this problem [here](http://solnic.eu/2012/04/11/get-rid-of-that-code-smell-control-couple.html).
+
+## Current Support in reek
+
+`reek` warns about control coupling when:
+
+* [Control-Parameter](Control-Parameter.md) - a method parameter or block parameter is the tested value in a conditional statement (as in the example below); or
+* [Boolean-Parameter](Boolean-Parameter.md) - a method parameter is defaulted to `true` or `false`.
+
+## Configuration
+
+Control Couple supports the [Basic Smell Options](Basic-Smell-Options.md).

data/docs/Control-Parameter.md

@@ -0,0 +1,29 @@
+# Control Parameter
+
+## Introduction
+
+`Control Parameter` is a special case of [Control Couple](Control-Couple.md)
+
+## Example
+
+A simple example would be the "quoted" parameter in the following method:
+
+```Ruby
+def write(quoted)
+  if quoted
+    write_quoted @value
+  else
+    write_unquoted @value
+  end
+end
+```
+
+Fixing those problems is out of the scope of this document but an easy solution could be to remove the "write" method alltogether and to move the calls to "write_quoted" / "write_unquoted" in the initial caller of "write".
+
+## Current Support in reek
+
+`reek` warns about control coupling when a method parameter or block parameter is the tested value in a conditional statement.
+
+## Configuration
+
+Control Couple supports the [Basic Smell Options](Basic-Smell-Options.md).

data/docs/Data-Clump.md

@@ -0,0 +1,44 @@
+# Data Clump
+
+## Introduction
+
+In general, a `Data Clump` occurs when the same two or three items frequently appear together in classes and parameter lists, or when a group of instance variable names start or end with similar substrings.
+
+The recurrence of the items often means there is duplicate code spread around to handle them. There may be an abstraction missing from the code, making the system harder to understand.
+
+## Example
+
+Given
+
+```Ruby
+class Dummy
+  def x(y1,y2); end
+  def y(y1,y2); end
+  def z(y1,y2); end
+end
+```
+
+`reek` would emit the following warning:
+
+```
+test.rb -- 1 warning:
+  [2, 3, 4]:Dummy takes parameters [y1, y2] to 3 methods (DataClump)
+```
+
+A possible way to fix this problem (quoting from [Martin Fowler](http://martinfowler.com/bliki/DataClump.html)):
+
+>> The first step is to replace data clumps with objects and use the objects whenever you see them. An immediate benefit is that you'll shrink some parameter lists. The interesting stuff happens as you begin to look for behavior to move into the new objects.
+
+## Current Support in Reek
+
+`reek` looks for a group of two or more parameters with the same names that are expected by three or more methods of a class.
+
+## Configuration
+
+Reek's Data Clump detector offers the [Basic Smell Options](Basic-Smell-Options.md), plus:
+
+| Option         | Value       | Effect  |
+| ---------------|-------------|---------|
+| max_copies     | integer | The maximum number of methods that are permitted to take the same group of parameters. Defaults to 2 |
+| min_clump_size | integer | The smallest number of parameters that can be reported as a clump. Defaults to 2 |
+

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,49 @@
+# 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.
+
+_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.
+
+## Example
+
+Running reek on:
+
+```Ruby
+class Warehouse
+  def sale_price(item)
+    (item.price - item.rebate) * @vat
+  end
+end
+```
+
+would report:
+
+```Bash
+Warehouse#total_price refers to item more than self (FeatureEnvy)
+```
+
+since this:
+
+```Ruby
+(item.price - item.rebate)
+```
+
+belongs to the Item class, not the Warehouse.
+
+## 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.
+
+## Differences to _Utility Function_
+
+_Feature Envy_ is only triggered if there are some references to self and _[Utility Function](Utility Function.md)_ is triggered if there are no references to self.
+
+## Configuration
+
+_Feature Envy_ supports the [Basic Smell Options](Basic-Smell-Options.md).