From e13bfabbaf11cafabfa1fef7cec9277cc06e6c8f Mon Sep 17 00:00:00 2001 From: Neil Carvalho Date: Fri, 14 Mar 2025 12:02:45 -0300 Subject: [PATCH 1/3] Use an opinionated set of rules for Rubocop Most projects that thoughtbot is working on currently did not start here. The "Use standard" recommendation comes from a time that that wasn't true. There are a few reasons not to use Standard in existing projects: - A large project does not already use Standard and retrofitting would be costly - Need or want Rubocop rules other than Standard's opinionated set --- ruby/README.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/ruby/README.md b/ruby/README.md index 4c2d87eb..d8713aac 100644 --- a/ruby/README.md +++ b/ruby/README.md @@ -2,7 +2,8 @@ [Sample 1](sample_1.rb) [Sample 2](sample_2.rb) -- Use [standard] +- 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. - Avoid conditional modifiers (lines that end with conditionals). [36491dbb9] - Avoid multiple assignments per line (`one, two = 1, 2`). [#109] - Avoid organizational comments (`# Validations`). [#63] From d7bd2d1de44d58f7180bacd4e1985e6be0ad6b1a Mon Sep 17 00:00:00 2001 From: Valerie Burzynski Date: Fri, 25 Apr 2025 16:49:06 -0500 Subject: [PATCH 2/3] link rubocop guideline to additional information --- .markdownlint-cli2.jsonc | 2 +- ruby/README.md | 4 +--- ...an opinionated set of rules for Rubocop.md | 24 +++++++++++++++++++ 3 files changed, 26 insertions(+), 4 deletions(-) create mode 100644 ruby/Use an opinionated set of rules for Rubocop.md 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..02b9fd7f --- /dev/null +++ b/ruby/Use an opinionated set of rules for Rubocop.md @@ -0,0 +1,24 @@ +# Use an opinionated set of rules for Rubocop + +Ruby code can be written in many different styles and still be syntatically 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 unnessary 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 + +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 From bb48251f0a84a5ea0fc01f2c495789f3334334c8 Mon Sep 17 00:00:00 2001 From: Valerie Burzynski Date: Fri, 9 May 2025 09:34:46 -0500 Subject: [PATCH 3/3] fix typos and add trade-offs for using standard --- ruby/Use an opinionated set of rules for Rubocop.md | 9 ++++++--- 1 file changed, 6 insertions(+), 3 deletions(-) diff --git a/ruby/Use an opinionated set of rules for Rubocop.md b/ruby/Use an opinionated set of rules for Rubocop.md index 02b9fd7f..ee5f320e 100644 --- a/ruby/Use an opinionated set of rules for Rubocop.md +++ b/ruby/Use an opinionated set of rules for Rubocop.md @@ -1,11 +1,12 @@ # Use an opinionated set of rules for Rubocop -Ruby code can be written in many different styles and still be syntatically correct. The presence of divergent style and +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 unnessary code churn. +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. +**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. @@ -16,6 +17,8 @@ There are, however, a few reasons one might choose not to introduce Standard in - 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