Comments (22)
👍
from ruby.
@ljharb I love the rationales.md
idea. It is the best of both worlds: concise style guide backed up with rationales. When can we start???
from ruby.
Immediately :-) PRs welcome! :-p
from ruby.
I'm a fan of this, especially if we enable rich linking in the short guide to the specific section in the long guide.
from ruby.
A link to the PR seems like a good, low-cost way to do it. I like that one.
If you do a separate rationales.md
, I think it'll be out of sync a lot. I wouldn't recommend a "long version" of the guide that repeats all the guidelines, either--then it will be even more out of sync.
Since these are style issues, a lot of the time there's no rationale other than "we wanted to pick a style so we picked this one." 😜
from ruby.
we could always of course add an appendix in the main file, then link down to it from the main rule. rationals.md
could also be an incomplete list, just existent for linking, rather than an expanded version of the main style guide
from ruby.
Even when the rationale is "the N forms are equivalent and we just like this one better" that's hugely valuable - it informs users which rules they don't have to consider too heavily before deviating from in their own projects.
As long as the rationale is immediately reachable, I will be happy. Requiring users to track down the appropriate PR is super hostile to people not intimately familiar with git/github.
imo this guide shouldn't be primarily or solely aimed at rubyists, it should be aimed at non-rubyists who want to use Ruby (especially newcomers to Ruby that work at Airbnb) - and as such, the rationale is pretty critical to understand as readers are learning the language.
from ruby.
I see two great ideas, a separate file for the rationales and the appendix that @kmsun07 proposed.
from ruby.
As long as "arbitrary consistency" is a valid rationale. I'm not being flippant or sarcastic. For many--I would say most--style rules, that's the reason. Otherwise I would have a hard time justifying, for example, two-space indentation vs. some other number of spaces.
from ruby.
Certainly the only reason to choose any number of spaces for indentation is "arbitrary consistency" but sure, that's fine to put as the rationale when that applies.
from ruby.
Will we go with the separate rationales.md
file? Or will we go with the appendix? If I had 1 gummy bear to distribute, I would give it to rationales.md
. What is everyone feeling? I can start once we all come to a consensus.
from ruby.
I gummy bear rationales.md
I don't think they need to get out of sync - we just make sure people submit PRs that touch both files.
from ruby.
I gummy bear rationales.md
from ruby.
I am getting a sugar high! I will start working on it after a couple more gummies.
from ruby.
gummy bear for rationales.md from me too
from ruby.
I'm reading the style guide again and a lot of the rules are already as short as possible with no rationale. The thing that takes up the most space are the examples. Are we wanting to extract the examples into the rationale?
from ruby.
Checkout this style guide, my absolute favorite: https://github.com/thoughtbot/guides/tree/master/style/ruby
from ruby.
We can do something similar, for example:
- Indent using 2 spaces Example
Clicking Example
will take you to the section in the rationales/examples with:
# bad
def foo
1
end
# good
def foo
1
end
from ruby.
Personally, I prefer having the example in the main guide because often the wording of the rule itself isn't clear enough for me to immediately understand what the rule is. By contrast, the rationale is truly optional knowledge.
from ruby.
@tommydangerous My initial reaction was "but the examples are so helpful!"
But then I saw your link to the more concise guide at Thoughtbot and I have to say, I love it. It's so easy to scan. I support your suggestion to move the examples out.
from ruby.
I will create a PR and we can see how it works.
from ruby.
This issue can be closed now, I believe, since rationales.md
exists.
from ruby.
Related Issues (20)
- Portugueses translate
- Broken link on http://airbnb.io/projects/ruby/ HOT 5
- Method chaining HOT 1
- AutoCorrect Bug HOT 4
- Upgrade to rubocop 0.59.1 HOT 8
- Could you clarify why there is many disabled cops? HOT 1
- RiskyActiverecordInvocation false positive HOT 3
- Support ruby 2.6 HOT 1
- Allowing symbols when specifying class for Airbnb/ClassName and Airbnb/FactoryClassUseString HOT 1
- Editorconfig for airbinb ruby? HOT 1
- unable to use because of the rubocop version HOT 4
- Any prediction on when a version will be released? HOT 7
- config/default.yml does not match Rubocop of the same version
- Any plans to depend on a more recent version of rubocop?
- Ruby 3.1.3 HOT 1
- Do not set DisableByDefault
- `RuboCop::Cop::Airbnb::ModuleMethodInWrongFile` returns incorrect error message when defining a method inside singleton class
- 1 HOT 1
- Nested or Compact Class and Module naming style?
- Rubocop dependency update to make VSC extension play well with it
Recommend Projects
-
React
A declarative, efficient, and flexible JavaScript library for building user interfaces.
-
Vue.js
🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
-
Typescript
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
-
TensorFlow
An Open Source Machine Learning Framework for Everyone
-
Django
The Web framework for perfectionists with deadlines.
-
Laravel
A PHP framework for web artisans
-
D3
Bring data to life with SVG, Canvas and HTML. 📊📈🎉
-
Recommend Topics
-
javascript
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
-
web
Some thing interesting about web. New door for the world.
-
server
A server is a program made to process requests and deliver data to clients.
-
Machine learning
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
-
Visualization
Some thing interesting about visualization, use data art
-
Game
Some thing interesting about game, make everyone happy.
Recommend Org
-
Facebook
We are working to build community through open source technology. NB: members must have two-factor auth.
-
Microsoft
Open source projects and samples from Microsoft.
-
Google
Google ❤️ Open Source for everyone.
-
Alibaba
Alibaba Open Source for everyone
-
D3
Data-Driven Documents codes.
-
Tencent
China tencent open source team.
from ruby.