reek 2.0.4 → 3.0.0

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.

data/docs/Uncommunicative-Method-Name.md

@@ -0,0 +1,24 @@
+# Uncommunicative Method Name
+
+## Introduction
+
+An `Uncommunicative Method Name` is a method name that doesn't communicate its intent well enough.
+
+Poor names make it hard for the reader to build a mental picture of what's going on in the code. They can also be mis-interpreted; and they hurt the flow of reading, because the reader must slow down to interpret the names.
+
+## Current Support in reek
+
+`Uncommunicative Method Name` checks for:
+
+* 1-character names
+* any name ending with a number
+* camelCaseVariableNames
+
+## Configuration
+
+`reek`'s Uncommunicative Method Name detector supports the [Basic Smell Options](Basic-Smell-Options.md), plus:
+
+| Option         | Value       | Effect  |
+| ---------------|-------------|---------|
+| `reject` | array of regular expressions | The set of regular expressions that `reek` uses to check for bad names. Defaults to `[/^[a-z]$/, /[0-9]$/, /[A-Z]/]`. |
+| `accept` | array of strings or regular expressions | Name that will be accepted (not reported) even if they match one of the `reject` expressions. |

data/docs/Uncommunicative-Module-Name.md

@@ -0,0 +1,23 @@
+# Uncommunicative Module Name
+
+## Introduction
+
+An `Uncommunicative Module Name` is a module name that doesn't communicate its intent well enough.
+
+Poor names make it hard for the reader to build a mental picture of what's going on in the code. They can also be mis-interpreted; and they hurt the flow of reading, because the reader must slow down to interpret the names.
+
+## Current Support in reek
+
+`Uncommunicative Module Name` checks for:
+
+* 1-character names
+* any name ending with a number
+
+## Configuration
+
+`reek`'s `Uncommunicative Module Name` detector supports the [Basic Smell Options](Basic-Smell-Options.md), plus:
+
+| Option         | Value       | Effect  |
+| ---------------|-------------|---------|
+| `reject` | array of regular expressions | The set of regular expressions that `reek` uses to check for bad names. Defaults to `[/^.$/, /[0-9]$/]`. |
+| `accept` | array of strings or regular expressions | Name that will be accepted (not reported) even if they match one of the `reject` expressions. Defaults to `['Inline::C']`.|

data/docs/Uncommunicative-Name.md

@@ -0,0 +1,16 @@
+# Uncommunicative Name
+
+## Introduction
+
+An `Uncommunicative Name` is a name that doesn't communicate its intent well enough.
+
+Poor names make it hard for the reader to build a mental picture of what's going on in the code. They can also be mis-interpreted; and they hurt the flow of reading, because the reader must slow down to interpret the names.
+
+## Current Support in Reek
+
+`reek` offers four related checks:
+
+* [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)

data/docs/Uncommunicative-Parameter-Name.md

@@ -0,0 +1,24 @@
+# Uncommunicative Parameter Name
+
+## Introduction
+
+An `Uncommunicative Parameter Name` is a parameter name that doesn't communicate its intent well enough.
+
+Poor names make it hard for the reader to build a mental picture of what's going on in the code. They can also be mis-interpreted; and they hurt the flow of reading, because the reader must slow down to interpret the names.
+
+## Current Support in reek
+
+`Uncommunicative Parameter Name` checks for:
+
+* 1-character names
+* any name ending with a number
+* camelCaseVariableNames
+
+## Configuration
+
+`reek`'s Uncommunicative Parameter Name detector supports the [Basic Smell Options](Basic-Smell-Options.md), plus:
+
+| Option         | Value       | Effect  |
+| ---------------|-------------|---------|
+| `reject` | array of regular expressions | The set of regular expressions that `reek` uses to check for bad names. Defaults to `[/^.$/, /[0-9]$/, /[A-Z]/]@. |
+| `accept` | array of strings or regular expressions | Name that will be accepted (not reported) even if they match one of the `reject` expressions. |

data/docs/Uncommunicative-Variable-Name.md

@@ -0,0 +1,24 @@
+# Uncommunicative Variable Name
+
+## Introduction
+
+An `Uncommunicative Variable Name` is a variable name that doesn't communicate its intent well enough.
+
+Poor names make it hard for the reader to build a mental picture of what's going on in the code. They can also be mis-interpreted; and they hurt the flow of reading, because the reader must slow down to interpret the names.
+
+## Current Support in Reek
+
+`Uncommunicative Variable Name` checks for:
+
+* 1-character names
+* any name ending with a number
+* camelCaseVariableNames
+
+## Configuration
+
+`reek`'s `Uncommunicative Variable Name` detector supports the [Basic Smell Options](Basic-Smell-Options.md), plus:
+
+| Option         | Value       | Effect  |
+| ---------------|-------------|---------|
+| `reject` | array of regular expressions | The set of regular expressions that `reek` uses to check for bad names. Defaults to `[/^.$/, /[0-9]$/, /[A-Z]/]`. |
+| `accept` | array of strings or regular expressions | Name that will be accepted (not reported) even if they match one of the `reject` expressions. Defaults to @['_']@.|

data/docs/Unused-Parameters.md

@@ -0,0 +1,27 @@
+## Introduction
+
+`Unused Parameter` refers to methods with parameters that are unused in scope of the method.
+
+Having unused parameters in a method is code smell because leaving dead code in a method can never improve the method and it makes the code confusing to read. 
+
+## Example
+
+Given:
+
+```Ruby
+class Klass
+  def unused_parameters(x,y,z)
+    puts x,y # but not z
+  end
+end
+```
+
+`reek` would emit the following warning:
+
+```
+[2]:Klass#unused_parameters has unused parameter 'z' (UnusedParameters)
+```
+
+## Configuration
+
+`Unused Parameter` offers the [Basic Smell Options](Basic-Smell-Options.md).

data/docs/Utility-Function.md

@@ -0,0 +1,44 @@
+# Utility Function
+
+## Introduction
+
+A _Utility Function_ is any instance method that has no dependency on the state of the instance.
+
+_Utility Function_ is heavily related to _[Feature Envy](Feature-Envy.md)_, please check out the explanation there why _Utility Function_ is something you should care about.
+
+## Example
+
+Given
+
+```Ruby
+class UtilityFunction
+  def showcase(argument)
+    argument.to_s + argument.to_i
+  end
+end
+```
+
+`reek` would report:
+
+```
+test.rb -- 2 warnings:
+  [2]:UtilityFunction#showcase doesn't depend on instance state (UtilityFunction)
+```
+
+## Current Support in reek
+
+_Utility Function_ will warn about any method that:
+
+* is non-empty
+* does not override an inherited method
+* calls at least one method on another object
+* doesn't use any of self's instance variables
+* doesn't use any of self's methods
+
+## Differences to _Feature Envy_
+
+_[Feature Envy](Feature-Envy.md)_ is only triggered if there are some references to self and _Utility Function_ is triggered if there are no references to self.
+
+## Configuration
+
+`reek`'s _Utility Function_ detector supports the [Basic Smell Options](Basic-Smell-Options.md).

data/docs/Versioning-Policy.md

@@ -0,0 +1,7 @@
+# Versioning Policy
+
+* CLI interface: Adding options is a non-breaking change, and would warrant an update of the minor version. Removing options is a breaking change and requires a major version update (we did this going to reek 2). Adding a report format probably also warrents a minor version upgrade.
+* API: We haven't really defined a 'public' API for using Reek programmatically, and we've only just started testing it. So, this is basically a blank slate at the moment. We will work on this as a part of the reek 3 release.
+* List of detected smells: Adding a smell warrants a minor release, removing a smell is a breaking change. This makes sense if you consider that the CLI allows running a single smell detector.
+* Consistency of detected smells: This is very hard to guarantee. If we fix a bug in one of the detectors, some fragrant code may become smelly, or vice versa. Right now we don't bother with this.
+* Smell configuration: The detectors are quite tolerant regarding configuration options that they don't recognize, so we regard any change here as only requiring a minor release.

data/docs/YAML-Reports.md

@@ -0,0 +1,111 @@
+# YAML Reports
+
+## Introduction
+
+`Reek`'s `--yaml` option writes on $stdout a YAML dump of the smells found. Each reported smell has a number of standard fields and a number of fields that are specific to the smell's type. The common fields are as follows:
+
+| Field         | Type       | Value  |
+| ---------------|-------------|---------|
+| source | string | The name of the source file containing the smell, or `$stdin` |
+| lines | array | The source file line number(s) that contribute to this smell |
+| context | string | The name of the class, module or method containing the smell |
+| class | string | The class to which this smell belongs |
+| subclass | string | This smell's subclass within the above class |
+| message | string | The message that would have been printed in a standard Reek report |
+| is_active | boolean | `false` if the smell is masked by a config file; `true` otherwise |
+
+All of these fields are grouped into hashes `location`, `smell` and `status` (see the examples below).
+
+## Examples
+
+Duplication:
+
+<pre>
+- !ruby/object:Reek::SmellWarning 
+  location: 
+    source: spec/samples/masked/dirty.rb
+    lines: 
+    - 5
+    - 7
+    context: Dirty#a
+  smell: 
+    class: Duplication
+    subclass: DuplicateMethodCall
+    occurrences: 2
+    call: puts(@s.title)
+    message: calls puts(@s.title) twice
+  status:
+    is_active: true
+</pre>
+
+[Nested Iterators](Nested-Iterators.md):
+
+<pre>
+- !ruby/object:Reek::SmellWarning 
+  location: 
+    source: spec/samples/masked/dirty.rb
+    lines: 
+    - 5
+    context: Dirty#a
+  smell: 
+    class: NestedIterators
+    subclass: ""
+    depth: 2
+    message: contains iterators nested 2 deep
+  status:
+    is_active: true
+</pre>
+
+[Uncommunicative Method Name](Uncommunicative-Method-Name.md):
+
+<pre>
+- !ruby/object:Reek::SmellWarning 
+  location: 
+    source: spec/samples/masked/dirty.rb
+    lines: 
+    - 3
+    context: Dirty#a
+  smell: 
+    class: UncommunicativeName
+    subclass: UncommunicativeMethodName
+    method_name: a
+    message: has the name 'a'
+  status:
+    is_active: false
+</pre>
+
+[Uncommunicative Variable Name](Uncommunicative-Variable-Name.md):
+
+<pre>
+- !ruby/object:Reek::SmellWarning 
+  location: 
+    source: spec/samples/masked/dirty.rb
+    lines: 
+    - 5
+    context: Dirty#a
+  smell: 
+    class: UncommunicativeName
+    subclass: UncommunicativeVariableName
+    variable_name: x
+    message: has the variable name 'x'
+  status:
+    is_active: true
+</pre>
+
+[Control Couple](Control-Couple.md):
+
+<pre>
+- !ruby/object:Reek::SmellWarning 
+  location: 
+    source: $stdin
+    lines: 
+    - 2
+    context: Turn#fred
+  smell: 
+    class: ControlCouple
+    subclass: BooleanParameter
+    parameter: arg
+    message: has boolean parameter 'arg'
+  status:
+    is_active: true
+</pre>

data/docs/yard_plugin.rb

@@ -0,0 +1,14 @@
+require 'yard'
+
+# Template helper to modify processing of links in HTML generated from our
+# markdown files.
+module LocalLinkHelper
+  # Rewrites links to (assumed local) markdown files so they're processed as
+  # {file: } directives.
+  def resolve_links(text)
+    text = text.gsub(%r{<a href="([^"]*.md)">([^<]*)</a>}, '{file:\1 \2}')
+    super text
+  end
+end
+
+YARD::Templates::Template.extra_includes << LocalLinkHelper

data/features/{ruby_api/api.feature → command_line_interface/basic_usage.feature}

@@ -1,20 +1,21 @@
-Feature: The Reek API maintains backwards compatibility
+Feature: The Reek CLI maintains backwards compatibility
   In order to use Reek without fuss
   As a developer
-  I want to have a stable API
+  I want to have a stable basic command line interface
 
   Scenario: the demo example reports as expected
-    When I run reek spec/samples/demo
+    Given the smelly file 'demo.rb' from the example in the README
+    When I run reek demo.rb
     Then the exit status indicates smells
     And it reports:
       """
-      spec/samples/demo/demo.rb -- 8 warnings:
+      demo.rb -- 8 warnings:
         [1]:Dirty has no descriptive comment (IrresponsibleModule)
         [3]:Dirty#awful has 4 parameters (LongParameterList)
         [3]:Dirty#awful has boolean parameter 'log' (BooleanParameter)
+        [3]:Dirty#awful has the parameter name 'x' (UncommunicativeParameterName)
         [5]:Dirty#awful has the variable name 'w' (UncommunicativeVariableName)
         [3]:Dirty#awful has unused parameter 'log' (UnusedParameters)
         [3]:Dirty#awful has unused parameter 'offset' (UnusedParameters)
-        [3]:Dirty#awful has unused parameter 'x' (UnusedParameters)
         [3]:Dirty#awful has unused parameter 'y' (UnusedParameters)
       """

data/features/command_line_interface/options.feature

@@ -39,6 +39,7 @@ Feature: Reek can be controlled using command-line options
                                              text (default)
                                              yaml
                                              json
+                                             xml
 
       Text format options:
               --[no-]color                 Use colors for the output (default: true)

data/features/command_line_interface/smell_selection.feature

@@ -4,15 +4,11 @@ Feature: Smell selection
   I want to be able to selectively activate smell detectors
 
   Scenario: --smell selects a smell to detect
-    When I run reek --no-line-numbers --smell DuplicateMethodCall spec/samples/two_smelly_files
+    Given a smelly file called 'smelly.rb'
+    When I run reek --no-line-numbers --smell UncommunicativeMethodName smelly.rb
     Then the exit status indicates smells
     And it reports:
       """
-      spec/samples/two_smelly_files/dirty_one.rb -- 2 warnings:
-        Dirty#a calls @s.title 2 times (DuplicateMethodCall)
-        Dirty#a calls puts(@s.title) 2 times (DuplicateMethodCall)
-      spec/samples/two_smelly_files/dirty_two.rb -- 2 warnings:
-        Dirty#a calls @s.title 2 times (DuplicateMethodCall)
-        Dirty#a calls puts(@s.title) 2 times (DuplicateMethodCall)
-      4 total warnings
+      smelly.rb -- 1 warning:
+        Smelly#m has the name 'm' (UncommunicativeMethodName)
       """