Create some RSpec Style Guide similar to the once we have for Ruby and Rails

[bbatsov]

It'd be nice if we had some repo about the best RSpec practices rubocop-rspec is enforcing. Right now it's a bit unclear where are some of the rules originating from and why are those the recommended ones.

[dgollahon]

Personally, I'd be very reluctant to maintain a separate style guide.

I have a counter-proposal / question:

What if there was a Cop API for adding metadata to each cop that could be exported? I've been wanting to something like this for years for a different tool I work on. I know we already parse out documentation comments, but maybe there could be an additional mechanism that records more detailed arguments for the cop.

Possible advantages:

1. Nothing to keep in sync / no extra repos or websites to manage.
2. We could add a --explain-cop flag or something that would spit out arguments for or against and provide more detail without leaving the terminal context.

This could be something simple-ish like having class macros that are something like:

class SomeCop < Cop
  argument_for_enabling('This cop helps you avoid common mistake X which ...')
  argument_against_enabling('Since rubocop performs static analyses, checking for method foo assumes the receiver is a Bar, but this can't be determined so there may be false positives.')

  # ...
end

Maybe the normal text documentation where the # good and # bad examples are could be converted into part of a macro system like this and stored in a more structured manner that could automatically be exported in various forms. In particular, it could be executable and assert that the documentation is in sync or automatically become part of the test suite. The idea could also be taken further for describing/documenting what all the configuration options do and why in some sort of dsl instead of just yaml.

I'm curious how you / others would feel about a system roughly like what I'm proposing where more information about the cop is actually encoded in the cop.

[Drenmi]

I believe many of the cops are at least inspired by Better Specs.

[bbatsov]

Well, we actually have a style guide now - https://github.com/rubocop-hq/rspec-style-guide/ (thanks to @pirj). We should link to it from the RSpec cops and keep refining/evolving it.

[pirj]

Closing as complete