reek 4.4.0 → 4.4.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 9e0d256e7194e6839716a3817b6fe951985f4fc8
-  data.tar.gz: ec2e207fe63cd0c8cd5b48071e660bd83ccb1cc6
+  metadata.gz: 6f4239287ce5d453034915801d47bd07738e0a09
+  data.tar.gz: 717f8ac8b8a9e0093a4aaa2ee9c5f739fd27be57
 SHA512:
-  metadata.gz: 6a2f747bdbded9c2610d934c23b07a72b001a93a9a9ed99d20b9e2bdea7c6ed5e7e667c8e05713b1e77e148294fb8e4cd34d606e197829744491db395a0c964b
-  data.tar.gz: 16d71aee67557e3f4d78cba1d45c8452032ccf76148c57b0c50650d0bff4f8fbcb4ecc9020df33a88746a80cce65235231e5b9a4f610e187a47a43baba27b1bf
+  metadata.gz: ccbb4be4cf7bb2d47ce72f5fd7d709ca3b3b4e49b95253aa549a14d62a7468a176c9b10cb1d21da9667963791c3f8eca66137e0f2dd03bd5507e65c94deb6953
+  data.tar.gz: 90eb9358f3f66271fa0a568e4582f9d473911723730a30e1b9de7771e5f79381832be59c3d511ddae81c614d772d67a6e49a07ddece6de756f482663976ee5ea

data/CHANGELOG.md

@@ -1,5 +1,11 @@
 # Change log
 
+## 4.4.1 (2016-09-13)
+
+* (troessner) Quote names in smell detector messages
+* (troessner) Make our CodeComment regex more lenient
+* (troessner) Fix UncommunicativeVariableName does not take regex configuration into account
+
 ## 4.4.0 (2016-08-24)
 
 * (waldyr) Add ignored nodes parameter to local_nodes

data/CONTRIBUTING.md

@@ -27,7 +27,9 @@ version, Ruby platform (MRI, JRuby, etc.), operating system.
 Try to provide a minimal example that reproduces the issue.
 Extra kudos if you can write it as a failing test. :)
 
-## Setup and Pull Request Basics
+## Contribute features, bugfixes, documentation
+
+### Getting started
 
 Fork Reek, then clone it, make sure you have
 [Bundler](http://bundler.io) installed, install dependencies
@@ -47,17 +49,52 @@ Once you’re sure your copy of Reek works create your own feature branch from o
 git checkout -b your_feature_or_fix_name
 ```
 
-Make sure you have read our [style guide](docs/style-guide.md) before you
+Make sure you have read our [style guide](docs/Style-Guide.md) before you
 start contributing.
 
 Then start hacking and add new tests which make sure that your new feature works or
 demonstrate that your fix was needed.
+
+### Tests
+
 Reek is using [Rspec](http://rspec.info/) for unit and functional testing and [cucumber]() for integration tests.
 
 When it comes to Rspec we're trying to follow [betterspecs](http://betterspecs.org/).
-Additonally you can find an excellent cheat sheet on how to write idiomatic Rspec [here](http://www.rubypigeon.com/posts/rspec-core-cheat-sheet).
+We're not using Rspec's [shared examples](https://www.relishapp.com/rspec/rspec-core/docs/example-groups/shared-examples) because we find
+them rather harming than helpful.
+You can find an excellent cheat sheet on how to write idiomatic Rspec [here](http://www.rubypigeon.com/posts/rspec-core-cheat-sheet).
+
+**Spec naming conventions**
+
+We do not use the popular "foo" / "bar" naming when it comes to the question "how to come up with good example names?".
+Instead, we use the [military alphabet](https://en.wikipedia.org/wiki/NATO_phonetic_alphabet) in ascending order
+which means that we would write this
+
+```Ruby
+class Foo
+  def bar(baz)
+    baz.quux
+  end
+end
+```
+
+rather like this:
+
+```Ruby
+class Alfa
+  def bravo(charlie)
+    charlie.delta
+  end
+end
+```
+
+### How to write new smell detectors
+
+Please see [our separate guide](docs/How-To-Write-New-Detectors.md) for this.
+
+### Finishing up
 
-We also care a lot about [good commit messages](http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html).
+We care a lot about [good commit messages](http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html).
 
 Once you’re happy with your feature / fix – or want to
 share it as a work-in-progress and request comments – once

data/README.md

@@ -210,15 +210,27 @@ Reek currently includes checks for some aspects of
 and more. See the [Code Smells](docs/Code-Smells.md)
 for up to date details of exactly what Reek will check in your code.
 
-Note that [Unused Private Method](docs/Unused-Private-Method.md) is disabled by default
+**Special configuration for controversial detectors:**
+
+[Unused Private Method](docs/Unused-Private-Method.md) is disabled by default
 because it is [kind of controversial](https://github.com/troessner/reek/issues/844) which means
-you have to explicitly activate in your configuration via
+you have to explicitly activate it in your configuration via
 
 ```Yaml
 UnusedPrivateMethod:
   enabled: true
 ```
 
+[Utility Function](docs/Utility-Function.md) is a [controversial detector](https://github.com/troessner/reek/issues/681)
+as well that can turn out to be really unforgiving.
+As a consequence, we made it possible to disable it for non-public methods like this:
+
+```Yaml
+---
+UtilityFunction:
+  public_methods_only: true
+```
+
 ## Configuration
 
 ### Command-line interface
@@ -356,7 +368,7 @@ end
 You can even pass in smell specific configuration settings:
 
 ```Ruby
-# :reek:NestedIterators: { max_allowed_nesting: 2 }
+# :reek:NestedIterators { max_allowed_nesting: 2 }
 def smelly_method foo
   foo.each {|bar| bar.each {|baz| baz.qux}}
 end

data/defaults.reek

@@ -115,7 +115,7 @@ UncommunicativeVariableName:
   - !ruby/regexp /[0-9]$/
   - !ruby/regexp /[A-Z]/
   accept:
-  - _
+  - !ruby/regexp /^_$/
 UnusedParameters:
   enabled: true
   exclude: []

data/docs/Basic-Smell-Options.md

@@ -19,7 +19,7 @@ exclusions for each smell.
 To stop Reek reporting smells in any method called `write` you might create a configuration file containing this:
 
 ```yaml
-ControlCouple: 
+DuplicateMethodCall:
   exclude:
   - write
 ```
@@ -27,7 +27,7 @@ ControlCouple:
 Or a little more sophisticated using a Ruby regex like this:
 
 ```yaml
-ControlCouple: 
+DuplicateMethodCall:
   exclude:
   - !ruby/regexp /write/
 ```

data/docs/Code-Smells.md

@@ -11,8 +11,10 @@ Reek currently includes checks for the following smells:
   * [Control Parameter](Control-Parameter.md)
 * [Data Clump](Data-Clump.md)
 * [Duplicate Method Call](Duplicate-Method-Call.md)
+* [Instance Variable Assumption](Instance-Variable-Assumption.md)
 * [Irresponsible Module](Irresponsible-Module.md)
 * [Large Class](Large-Class.md), including
+  * [Too Many Constants](Too-Many-Constants.md)
   * [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)
@@ -23,8 +25,10 @@ Reek currently includes checks for the following smells:
 * [Nested Iterators](Nested-Iterators.md)
 * [Prima-Donna-Method](Prima-Donna-Method.md)
 * [Simulated Polymorphism](Simulated-Polymorphism.md), including
+  * [Manual Dispatch](Manual-Dispatch.md)
   * [Nil Check](Nil-Check.md)
   * [Repeated Conditional](Repeated-Conditional.md)
+* [Subclassed From Core Class](Subclassed-From-Core-Class.md)
 * [Too Many Statements](Too-Many-Statements.md)
 * [Uncommunicative Name](Uncommunicative-Name.md), including
   * [Uncommunicative Method Name](Uncommunicative-Method-Name.md)

data/docs/How-To-Write-New-Detectors.md

@@ -0,0 +1,116 @@
+## How to write new detectors
+
+### Outline what you have in mind
+
+Before starting to code you should discuss the overall idea for your new smell detector with
+us in a corresponding github issue.
+We all should have a solid understanding of what this detector actually reports, the edgecases
+it covers and the overall rationale behind it.
+
+### Structure
+
+All smell detectors reside in `lib/reek/smells` and have the following base structure:
+
+```Ruby
+require_relative 'smell_detector'
+require_relative 'smell_warning'
+
+module Reek
+  module Smells
+    #
+    # Here goes your introduction for this detector.
+    #
+    # See {file:docs/Your-Detector.md} for details.
+    class YourDetector < SmellDetector
+      def self.contexts
+        [:class] # In case you're operating on class contexts only - just an example.
+      end
+
+      #
+      # Here you should document what you expect "ctx" to look like.
+      #
+      # @return [Array<SmellWarning>]
+      #
+      def sniff(ctx)
+        # "found_smells" below is just an abstraction for
+        # "find the smells in question" and iteratore over them.
+        # This can just be a method but it can also be a more sophisticated set up.
+        # Check out other smell detectors to get a feeling for what to do here.
+        found_smells(ctx).map do |smell|
+          # "smell_warning" is defined in SmellDetector and should be used by you
+          # to construct smell warnings
+          smell_warning(
+            context: ctx,
+            lines: [], # lines on which the smell was detected
+            message: "...", # the message that is printed on STDOUT
+            # whatever you interpolate into the "message" should go into
+            # parameters below - if you do not interpolate anything you
+            # can omit this
+            parameters: { })
+          end
+        end
+      end
+
+      private
+
+      # Here goes everything you need for finding smells.
+    end
+  end
+end
+```
+
+### Documentation
+
+* Above every `SmellDetector::sniff` method it should be documented what the expected AST is
+* Every detector should have a separate documentation page in /docs. You can
+  take any arbitrary existing smell detector documentation page as template (since
+  they all have the same structure already)
+* The detector should be listed under [Code Smells](docs/Code-Smells.md)
+
+### Rspec examples
+
+All smell detector specs start out with 2 generic examples like below - the second one
+only if it makes sense.
+Here's what it looks like for `UncommunicativeVariableName`:
+
+```Ruby
+it 'reports the right values' do
+  src = <<-EOS
+    def alfa
+      bravo = 5
+    end
+  EOS
+
+  expect(src).to reek_of(:UncommunicativeVariableName,
+                         lines:   [2],
+                         context: 'alfa',
+                         message: "has the variable name 'bravo'",
+                         source:  'string',
+                         name:    'bravo')
+end
+
+it 'does count all occurences' do
+  src = <<-EOS
+    def alfa
+      bravo = 3
+      charlie = 7
+    end
+  EOS
+
+  expect(src).to reek_of(:UncommunicativeVariableName,
+                         lines: [2],
+                         name:  'bravo')
+  expect(src).to reek_of(:UncommunicativeVariableName,
+                         lines: [3],
+                         name:  'charlie')
+end
+```
+
+The following examples should then cover the detector specific features.
+
+### Cucumber features
+
+We are trying to write as few Cucumber features as possible.
+Normally, there should be no need to write a new feature for a new smell detector.
+If you feel like this is necessary in this case, please discuss this with us via
+github issue or in your work-in-progress pull request before doing anything.

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

@@ -25,7 +25,7 @@
                                           |                                                          |
                                           |                                                          |
                                 ReekCommand (cli/reek_command)                                       |
-                                * uses a reporter (report/report)                                |
+                                * uses a reporter (report/report)                                    |
                                 * uses a SourceLocator (source/source_locator)                       |
                                 /         |         \                                                |
                                /          |          \                                               |
@@ -41,9 +41,8 @@
                                   * 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)
                                   * builds a tree of Contexts using ContextBuilder
-                                  * runs the smell detectors from the SmellRepository above on each of the contexts
+                                  * tells the SmellRepository above to run each of its smell detectors above on each of the contexts
                                   /       |       \
                                  /        |        \
                                 /         |         \
@@ -51,7 +50,7 @@
                                 \         |         /
                                  \        |        /
                                   \       |       /
-                                   WarningCollector
+                                   SmellRepository
                                           |
                                           |
                                           |

data/docs/Instance-Variable-Assumption.md

@@ -0,0 +1,134 @@
+# Instance Variable Assumption
+
+## Introduction
+
+Classes should not assume that instance variables are set or present outside of the current class definition.
+
+Good:
+
+```Ruby
+class Foo
+  def initialize
+    @bar = :foo
+  end
+
+  def foo?
+    @bar == :foo
+  end
+end
+```
+
+Good as well:
+
+```Ruby
+class Foo
+  def foo?
+    bar == :foo
+  end
+
+  def bar
+    @bar ||= :foo
+  end
+end
+```
+
+Bad:
+
+```Ruby
+class Foo
+  def go_foo!
+    @bar = :foo
+  end
+
+  def foo?
+    @bar == :foo
+  end
+end
+```
+
+## Example
+
+Running Reek on:
+
+```Ruby
+class Dummy
+  def test
+    @ivar
+  end
+end
+```
+
+would report:
+
+```Bash
+  [1]:InstanceVariableAssumption: Dummy assumes too much for instance variable @ivar [https://github.com/troessner/reek/blob/master/docs/Instance-Variable-Assumption.md]
+```
+
+Note that this example would trigger this smell warning as well:
+
+```Ruby
+class Parent
+  def initialize(omg)
+    @omg = omg
+  end
+end
+
+class Child < Parent
+  def foo
+    @omg
+  end
+end
+```
+
+The way to address the smell warning is that you should create an `attr_reader` to use `@omg` in the subclass and not access `@omg` directly like this:
+
+```Ruby
+class Parent
+  attr_reader :omg
+
+  def initialize(omg)
+    @omg = omg
+  end
+end
+
+class Child < Parent
+  def foo
+    omg
+  end
+end
+```
+
+Directly accessing instance variables is considered a smell because it [breaks encapsulation](http://designisrefactoring.com/2015/03/29/organizing-data-self-encapsulation/) and makes it harder to reason about code.
+
+If you don't want to expose those methods as public API just make them private like this:
+
+```Ruby
+class Parent
+  def initialize(omg)
+    @omg = omg
+  end
+
+  private
+  attr_reader :omg
+end
+
+class Child < Parent
+  def foo
+    omg
+  end
+end
+```
+
+
+## Current Support in Reek
+
+An instance variable must:
+
+* be set in the constructor
+* or be accessed through a method with lazy initialization / memoization.
+
+If not, _Instance Variable Assumption_ will be reported.
+
+## Configuration
+
+_Instance Variable Assumption_ supports the [Basic Smell Options](Basic-Smell-Options.md).