diff --git a/.markdownlint-cli2.jsonc b/.markdownlint-cli2.jsonc index 5c82619e..2ccda18a 100644 --- a/.markdownlint-cli2.jsonc +++ b/.markdownlint-cli2.jsonc @@ -149,7 +149,7 @@ /* MD052 - Reference links and images should use a label that is defined */ "reference-links-images": { - "shortcut_syntax": true + "shortcut_syntax": false }, /* MD053 - Link and image reference definitions should be needed */ diff --git a/ruby/README.md b/ruby/README.md index d8713aac..1f1e5c68 100644 --- a/ruby/README.md +++ b/ruby/README.md @@ -2,8 +2,7 @@ [Sample 1](sample_1.rb) [Sample 2](sample_2.rb) -- Use an opinionated set of rules for Rubocop. Prefer [standard] for new projects. - - Having an already decided configuration removes bikeshedding on what a Rubocop configuration should be. +- [Use an opinionated set of rules for Rubocop](./Use an opinionated set of rules for Rubocop.md) - Avoid conditional modifiers (lines that end with conditionals). [36491dbb9] - Avoid multiple assignments per line (`one, two = 1, 2`). [#109] - Avoid organizational comments (`# Validations`). [#63] @@ -42,7 +41,6 @@ - Prefer `private` when indicating scope. Use `protected` only with comparison methods like `def ==(other)`, `def <(other)`, and `def >(other)`. -[standard]: https://github.com/testdouble/standard [#63]: https://github.com/thoughtbot/guides/pull/63 [#109]: https://github.com/thoughtbot/guides/pull/109 [#122]: https://github.com/thoughtbot/guides/pull/122 diff --git a/ruby/Use an opinionated set of rules for Rubocop.md b/ruby/Use an opinionated set of rules for Rubocop.md new file mode 100644 index 00000000..ee5f320e --- /dev/null +++ b/ruby/Use an opinionated set of rules for Rubocop.md @@ -0,0 +1,27 @@ +# Use an opinionated set of rules for Rubocop + +Ruby code can be written in many different styles and still be syntactically correct. The presence of divergent style and +format can disrupt communication as well as complicate feature development. Code that exhibits a consistent style is +easier to understand and maintain. The absence of consistent enforced style can result in unnecessary code churn. + +**Therefore:** Use an opinionated set of rules for Rubocop when coding in Ruby. + +- Prefer [standard] for new projects. +- By employing an already decided configuration, you avoid bikeshedding on what the Rubocop configuration should be. +- Code that is consistently formatted and styled will be easier to work with. + +There are, however, a few reasons one might choose not to introduce Standard in a project: + +- Change for the sake of change can be disruptive +- An existing project may already employ it's own opinionated configuration of Rubocop and that set of rules is working. +- A large project, which does not already use Standard, might require a costly amount of time to refactor and retrofit + existing code to conform to a new set of conventions. +- There exists a need or desire to use Cops which are disabled by Standard +- [standard] presents a lightweight but sensible set of style rules to focus on coding +- [standard] prevents you from using cops that it disables + +Overall, the goal is to increase the quality and consistency of code while not getting distracted by disproportionally +minor or trivial details. It's more important for an implementation team to agree to follow shared conventions than it +is to enforce a specific configuration. + +[standard]: https://github.com/testdouble/standard