README.md in reek-4.8.2 vs README.md in reek-5.0.0
- old
+ new
@@ -37,17 +37,22 @@
* [](https://travis-ci.org/troessner/reek?branch=master)
* [](https://badge.fury.io/rb/reek)
* 
* 
-* [](https://gemnasium.com/github.com/troessner/reek)
* [](https://inch-ci.org/github/troessner/reek)
* [](https://codeclimate.com/github/troessner/reek)
* [](https://codebeat.co/projects/github-com-troessner-reek)
* 
* 
+## Reek 5 is out!
+
+Reek 5 is out and with it a bunch of breaking changes. If you're a new user you can just
+continue with the quickstart below. If you're a Reek 4 user and would like to upgrade to 5, don't
+worry, this shouldn't take you more than 10 minutes. Check out our [Upgrade Guide](docs/Reek-4-to-Reek-5-migration.md).
+
## Quickstart
Reek is a tool that examines Ruby classes, modules and methods and reports any
[Code Smells](docs/Code-Smells.md) it finds.
@@ -82,11 +87,11 @@
```
Reek will report the following code smells in this file:
```
-$ reek --no-wiki-links demo.rb
+$ reek --no-documentation demo.rb
Inspecting 1 file(s):
S
demo.rb -- 2 warnings:
[4]:UncommunicativeMethodName: Smelly#x has the name 'x'
@@ -95,12 +100,10 @@
## Supported Ruby versions
Reek is officially supported for the following CRuby versions:
- - 2.1
- - 2.2
- 2.3
- 2.4
- 2.5
Other Ruby implementations (like Rubinius or JRuby) are not officially supported but should work as well.
@@ -252,16 +255,17 @@
### Configuration file
#### Configuration loading
Configuring Reek via a configuration file is by far the most powerful way.
+Reek expects this filename to be `.reek.yml` but you can override this via the CLI `-c` switch (see below).
-There are three ways of passing Reek a configuration file:
+There are three ways of passing Reek the configuration file:
1. Using the CLI `-c` switch (see [_Command-line interface_](#command-line-interface) above)
-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
+2. Having the configuration file either in your current working directory or in a parent directory (more on that later)
+3. Having the configuration file in your home directory
The order in which Reek tries to find such a configuration
file is exactly the above: first it 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
@@ -275,91 +279,136 @@
#### Configuration options
We put a lot of effort into making Reek's configuration as self explanatory as possible so the
best way to understand it is by looking at a simple
-example (e.g. `config.reek` in your project directory):
+example (e.g. `.reek.yml` in your project directory):
```yaml
---
### Generic smell configuration
-# You can disable smells completely
-IrresponsibleModule:
- enabled: false
+detectors:
+ # You can disable smells completely
+ IrresponsibleModule:
+ enabled: false
+
+ # You can use filters to silence Reek warnings.
+ # Either because you simply disagree with Reek (we are not the police) or
+ # because you want to fix this at a later point in time.
+ NestedIterators:
+ exclude:
+ - "MyWorker#self.class_method" # should be refactored
+ - "AnotherWorker#instance_method" # should be refactored as well
+
+ # A lot of smells allow fine tuning their configuration. You can look up all available options
+ # in the corresponding smell documentation in /docs. In most cases you probably can just go
+ # with the defaults as documented in defaults.reek.yml.
+ DataClump:
+ max_copies: 3
+ min_clump_size: 3
-# You can use filters to silence Reek warnings.
-# Either because you simply disagree with Reek (we are not the police) or
-# because you want to fix this at a later point in time.
-NestedIterators:
- exclude:
- - "MyWorker#self.class_method" # should be refactored
- - "AnotherWorker#instance_method" # should be refactored as well
-
-# A lot of smells allow fine tuning their configuration. You can look up all available options
-# in the corresponding smell documentation in /docs. In most cases you probably can just go
-# with the defaults as documented in defaults.reek.
-DataClump:
- max_copies: 3
- min_clump_size: 3
-
### Directory specific configuration
# You can configure smells on a per-directory base.
# E.g. the classic Rails case: controllers smell of NestedIterators (see /docs/Nested-Iterators.md) and
# helpers smell of UtilityFunction (see docs/Utility-Function.md)
-"web_app/app/controllers":
- NestedIterators:
- enabled: false
-"web_app/app/helpers":
- UtilityFunction:
- enabled: false
+# Note that we only allow configuration on a directory level, not a file level, so all paths have to point to directories.
+directories:
+ "web_app/app/controllers":
+ NestedIterators:
+ enabled: false
+ "web_app/app/helpers":
+ UtilityFunction:
+ enabled: false
### Excluding directories
# Directories below will not be scanned at all
exclude_paths:
- lib/legacy
- lib/rake/legacy_tasks
```
+As you see above, Reek's configuration consists of 3 different sections denoted by 3 different keys:
+
+* detectors
+* directories
+* exclude_paths
+
+Whatever you add to your configuration should be scoped under one of those keys.
+
If you have a directory directive for which a default directive exists, the more specific
one (which is the directory directive) will take precedence.
This configuration for instance:
```yaml
---
-IrresponsibleModule:
- enabled: false
-
-TooManyStatements:
- max_statements: 5
-
-"app/controllers":
+detectors:
+ IrresponsibleModule:
+ enabled: false
+
TooManyStatements:
- max_statements: 10
+ max_statements: 5
```
translates to:
* IrresponsibleModule is disabled everywhere
* TooManyStatements#max_statements is 10 in "app/controllers"
* TooManyStatements#max_statements is 5 everywhere else
-For more details please check out the [Basic Smell Options](docs/Basic-Smell-Options.md)
-which are supported by every smell type. As you can see above, certain smell
-types offer a configuration that goes beyond that of the basic smell options, for instance
+Every smell detector supports our [Basic Smell Options](docs/Basic-Smell-Options.md). As you can see above,
+certain smell types offer a configuration that goes beyond that of the basic smell options, for instance
[Data Clump](docs/Data-Clump.md).
All options that go beyond the [Basic Smell Options](docs/Basic-Smell-Options.md)
are documented in the corresponding smell type /docs page (if you want to get a quick overview over all possible
-configurations you can also check out [the `default.reek` file in this repository](defaults.reek).
+configurations you can also check out [the `defaults.reek.yml` file in this repository](docs/defaults.reek.yml).
Note that you do not need a configuration file at all.
-If you're fine with all the [defaults](defaults.reek) we set you can skip this completely.
+If you're fine with all the [defaults.reek.yml](docs/defaults.reek.yml) we set you can skip this completely.
+Don't worry about introducing a mistake in your configuration file that might go unnoticed - Reek uses a
+schema to validate your configuration against on start up and will faily loudly in case you
+misspelled an option or used the wrong data type for a value like this:
+
+```
+Error: We found some problems with your configuration file: [/detectors/DetectorWithTypo] key 'DetectorWithTypo:' is undefined.
+```
+
+Reek takes one configuration file and one configuration file only with `.reek.yml` being the default name.
+
+In case you have to have one or more configuration files in the directory (e.g. you're
+toying around with different, mutually exclusive settings) you need to tell Reek
+explicitly which file to use via `reek -c config.reek`.
+
+### Source code comments
+
+In case you need to suppress a smell warning and you can't or don't want to
+use configuration files for whatever reasons you can also use special
+source code comments like this:
+
+```Ruby
+# This method smells of :reek:NestedIterators
+def smelly_method foo
+ foo.each {|bar| bar.each {|baz| baz.qux}}
+end
+```
+
+You can even pass in smell specific configuration settings:
+
+```Ruby
+# :reek:NestedIterators { max_allowed_nesting: 2 }
+def smelly_method foo
+ foo.each {|bar| bar.each {|baz| baz.qux}}
+end
+```
+
+This is an incredibly powerful feature and further explained under [Smell Suppresion](docs/Smell-Suppression.md).
+
### Generating a 'todo' list
Integrating tools like Reek into an existing larger codebase can be daunting when you have to fix
possibly hundreds or thousands of smell warnings first.
Sure you could manually disable smell warnings like shown above but depending on the size of your
@@ -402,46 +451,10 @@
```
`other_configuration.reek` will simply be ignored (as outlined before, Reek
is supposed to have one configuration file and one file only).
-### Beware of multiple configuration files
-
-Reek takes one configuration file and one configuration file only.
-
-If you have more than one configuration file in the same directory Reek
-will not know what configuration file to use. If this happens Reek will
-print a warning on STDERR and exit with the failure exit status 1.
-
-In case you have to have one or more configuration files in the directory (e.g. you're
-toying around with different, mutually exclusive settings) you need to tell Reek
-explicitly which file to use via `reek -c config.reek`.
-
-### Source code comments
-
-In case you need to suppress a smell warning and you can't or don't want to
-use configuration files for whatever reasons you can also use special
-source code comments like this:
-
-```Ruby
-# This method smells of :reek:NestedIterators
-def smelly_method foo
- foo.each {|bar| bar.each {|baz| baz.qux}}
-end
-```
-
-You can even pass in smell specific configuration settings:
-
-```Ruby
-# :reek:NestedIterators { max_allowed_nesting: 2 }
-def smelly_method foo
- foo.each {|bar| bar.each {|baz| baz.qux}}
-end
-```
-
-This is an incredible powerful feature and further explained under [Smell Suppresion](docs/Smell-Suppression.md).
-
## Usage
Besides the obvious
```Bash
@@ -557,27 +570,28 @@
Making Reek "Rails"-friendly is fairly simple since we support directory specific configurations (`directory directives` in Reek talk).
Just add this to your configuration file:
```Yaml
-"app/controllers":
- IrresponsibleModule:
- enabled: false
- NestedIterators:
- max_allowed_nesting: 2
- UnusedPrivateMethod:
- enabled: false
- InstanceVariableAssumption:
- enabled: false
-"app/helpers":
- IrresponsibleModule:
- enabled: false
- UtilityFunction:
- enabled: false
-"app/mailers":
- InstanceVariableAssumption:
- enabled: false
+directories:
+ "app/controllers":
+ IrresponsibleModule:
+ enabled: false
+ NestedIterators:
+ max_allowed_nesting: 2
+ UnusedPrivateMethod:
+ enabled: false
+ InstanceVariableAssumption:
+ enabled: false
+ "app/helpers":
+ IrresponsibleModule:
+ enabled: false
+ UtilityFunction:
+ enabled: false
+ "app/mailers":
+ InstanceVariableAssumption:
+ enabled: false
```
Be careful though, Reek does not merge your configuration entries, so if you already have a directory directive for "app/controllers" or "app/helpers" you need to update those directives instead of copying the above YAML sample into your configuration file.
## Integrations
@@ -586,9 +600,10 @@
* [Vim plugin](https://github.com/rainerborene/vim-reek)
* [TextMate Bundle](https://github.com/peeyush1234/reek.tmbundle)
* [Atom plugin](https://atom.io/packages/linter-reek)
* [SublimeLinter plugin](https://packagecontrol.io/packages/SublimeLinter-contrib-reek)
+* [VS Code plugin](https://github.com/rubyide/vscode-ruby)
* [Emacs plugin](https://github.com/hanmoi-choi/reek-emacs)
### Projects that use or support us
* [overcommit](https://github.com/brigade/overcommit) - a Git commit hook manager with support for