Proposal of new documentation for beginner rubyist

[yyh-gl]

Problem

I think that RuboCop is good tool for beginner rubyist.
Because I learned general ruby coding style from RuboCop.

But, Using RuboCop is difficult for me when I had touched RuboCop first time.
I think where is error!
What is error!
Maybe other beginner also feel difficult.

I think the reason that beginner feel difficult are following.

• Good style sample is here. But we don't have link to this page from report.
• Beginner can't understand view of report.
  • ex.) What is .C (following)

$ bundle exec rubocop
Inspecting 2 files
.C

Offenses:

Gemfile:1:11: C: Metrics/LineLength: Line is too long. [29/10]
# frozen_string_literal: true
          ^^^^^^^^^^^^^^^^^^^
Gemfile:3:11: C: Metrics/LineLength: Line is too long. [31/10]
# source 'https://rubygems.org'
          ^^^^^^^^^^^^^^^^^^^^^
Gemfile:6:11: C: Metrics/LineLength: Line is too long. [69/10]
git_source(:github) { |repo_name| "https://github.com/#{repo_name}" }
          ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Gemfile:8:11: C: Metrics/LineLength: Line is too long. [29/10]
gem 'rubocop', require: false
          ^^^^^^^^^^^^^^^^^^^

2 files inspected, 4 offenses detected

Solution

I suggest new documentation for beginner.
This documentation includes following items.

• How to read the report

  • ex.) The meaning of .C
  • ex.) The meaning of Gemfile:1:11 (What is the last number.)

• Link to sample code of good style

  • It is difficult to add link to good style sample into report. so I think RuboCop's documentation should suggest how to find the good style.

ex.) RuboCop documentaion suggest below.

You copy Metrics/LineLength and search in official documentation.

Gemfile:8:11: C: Metrics/LineLength: Line is too long. [29/10]
gem 'rubocop', require: false
          ^^^^^^^^^^^^^^^^^^^

I think if beginners know how to find solution, beginners resolve that problem himself.

RuboCop version

$ rubocop -V
0.57.2 (using Parser 2.5.1.0, running on ruby 2.5.0 x86_64-darwin17)

[Drenmi]

I've been thinking about this quite a bit. We do have an --extra-details flag, but it doesn't appear to be doing anything at the moment. What do you think about a "verbose" mode @bbatsov?

[yyh-gl]

I think --extra-details flag (more detail offenses message) is good for beginner.
That way, it will be easy for learning Ruby Good Code.

I hope --extra-details flag show the detail way to resolve offenses.
For example, RuboCop show good style with offenses message.

[Vasfed]

Other similar point is showing not only what is incorrect, but also a brief explanation on why

[yyh-gl]

Certainly, the explanation of the current RuboCop may be sufficient.
Because beginners can grow by looking for some solution by themselves based on the given information if there is something they do not understand.

About --extra-details, I will consider what is good for beginner.