RuboCop-notes
About RuboCop and Cops
A gem maintained by the company provide a style guide for RuboCop, along with custom linters. This project uses that gem.
:::code source="../../../uala-core/Gemfile" title="uala-core/Gemfile" range="18-21" :::
Configuration files
The RuboCop's configuration is splitted among serveral files.
The file containing the cops shared by all the projects is shared/.rubocop.yml.
All the projects contains two more files in their root directories: .rubocop.yml and .rubocop_todo.yml.
The .rubocop_todo.yml is autogenerated by RuboCop, it's there mostly to silence any warning from RuboCop. New cops shouldn't be added here.
The .rubocop.yml is the actual file used by RuboCop, it includes shared/.rubocop.yml and the project's .rubocop_todo.yml. It's the place to add project specific cops.
How to (re)generate the TODO file
If needed, to regenerate the RuboCop's TODO file use the command bin/rubocop --regenerate-todo. It will execute RuboCop to generate a configuration file using the options found in the header comment of .rubocop_todo.yml.
If the project hasn't a .rubocop_todo.yml already, to generate it use the following command:
bin/rubocop --auto-gen-config --auto-gen-only-exclude --exclude-limit 10000
How to configure or disable cops
The goal is to get no warning from RuboCop, but the law enforced by RuboCop is not always wise.
It may is useful to change a cop configuration to enforce a different style, for example just because the default RuboCop style doesn't match our preferred style (see shared/.rubocop.yml for few examples).
Sometimes it is even useful to disable a rule altogether, for example:
def initialize(some_param) # rubocop:disable Lint/MissingSuper
# I'm definitely sure I don't want to call the super class initializer!
There are three ways to disable a cop: within source code, per file, or globally. As a general rule, limit as much as possible the scope where the cop is disabled, i.e. prefer to disable a cop within source code over disabling it for the whole file.
When in doubt it is not evident, leave a comment to explain why a cop is disabled.
Choose a style
To configure the style a cop accepts, see under the "Configurable attributes" section of the cop in the RuboCop's documentation. The Layout/ArrayAlignment cop is a good example of this
Disable cops within source code
Cops can be disabled (but not configured) within source code by using comments like:
# rubocop: disable Layout/ArrayAlignment
# From here you can align arrays however you like.
# But remember to enable the cop when finished!
# rubocop: enable Layout/ArrayAlignment
Cops can be disabled for a single line using an end of line comment, as an (not so good) example:
no_one_will_read_me = 0 # rubocop: disable Lint/UselessAssignment
Disabling cops per file
To disable a cop for specific files (or files matching a glob):
Layout/ArrayAlignment:
Exclude:
- path/to/file/relative/to/where/this/config/file/is
The file paths must be relative to the location of the .rubocop.yml they are written in, i.e. in shared/.rubocop.yml to exclude a file a path like this must be used: ../uala-main/app/*.
Disabling cops globally
To disable a cop for any file of a project put the following in the project's .rubocop.yml (or in shared/.rubocop.yml to disable for any project):
Layout/ArrayAlignment:
Enabled: false
Analyze and prune TODO files
To list the cops in TODO files use the task rubocop:analyze_todo that lists the cops in descending order of number of occurrences:
bin/rails rubocop:analyze_todo LIMIT=10 GROUP=Layout
This command lists the cops of the Layout group up to ten offences (the default). If no GROUP variable is specified cops from all groups are listed.
To remove a cop from the TODO file and fixing the related offences use the task rubocop:remove_todo:
bin/rails rubocop:remove_todo RULE=Layout/LineContinuationLeadingSpace
This command removes the cop entry from the current project's TODO file. If the cop supports auto correction it will also run rubocop -A to fix the offences. Defining the environment variable AUTO_COMMIT=1 the changes made by rubocop -A will be commited.