From: shevegen@... Date: 2017-11-16T15:01:24+00:00 Subject: [ruby-core:83799] [Ruby trunk Feature#14112] Follow style conventions for Ruby code Issue #14112 has been updated by shevegen (Robert A. Heiler). I personally am against a "style guide". Ruby's old philosophy was partially inspired by perl - more than one way to do things. In an old interview by matz ( http://www.artima.com/intv/ruby3.html ) he said this too: "Ruby inherited the Perl philosophy of having more than one way to do the same thing. I inherited that philosophy from Larry Wall, who is my hero actually. I want to make Ruby users free. I want to give them the freedom to choose. People are different. People choose different criteria. But if there is a better way among many alternatives, I want to encourage that way by making it comfortable." I think that a "one true universal style guide" is antithematic to ruby. Furthermore, there is actually an "inofficial" style guide - which is what the ruby parser allows you to do. :) In particular this is my biggest problem with the style guide that is used by rubocop. Rubocop enforces ONE particular style - but the ruby parser allows you to have a lot more freedom in how YOU want to write. Yes, other people may not always write the "cleanest" code and what not, but you have the same situation applied in reverse. I give you an example. Take @@foo variables. I do not like them; I do not hate them either. More importantly though, I do not need them - and so I do not have to use them. The same applies to many other concepts in ruby, be it the lambda operator which I do not use, or the new hash notation, which I actually use sometimes (since it can lead to more concise code), or the lonely person operator, which I also do not use (but notice how it was added; a ruby hacker had a need and use case, matz agreed with the use case and the operator was added, so ruby hackers also have some ways to influence the evolution of ruby, which is good, even if I personally don't use the person-staring-at-a-dot operator). If I remember correctly, rubocop allows you to define any style, and then even enforce it + add the autocorrect option. Which is also good. I just contest that there SHOULD be "one true style - and only one true style alone". As for your comment about Ruby documentation, I am not completely against it. Ideally, all methods should be: - Documented, even if only briefly. - Have some usage examples that make sense. I think the rest of it is a bit difficult to enforce, since there are many different people writing the documentation. Some know the english language very well, others struggles slightly (even among the japanese hackers, there are HUGE differences; although from my experience, many japanese ruby hackers have almost perfect written english; just the talking in english isn't what they seem to love the most :) ). Martin wrote: > while a lot of its rules look reasonable, and a lot of others look > well-intended, I don't like others at all. I think that happens > for most people Yep, I agree here, in particular for code. I personally have less of an issue in regards to documentation, and I understand this part in the suggestion by Ana somewhat. Perhaps for ruby 3.x we can also think about some PR changes to suggest for a better documentation in general or a more "useful" documentation for ruby, including the current layout. I mean, the documentation in ruby is ok, it is useful too for the most part. I don't think it is really ... very good though and can possibly be improved, but this can probably come at a later time for ruby 3.x. Xmas is in about 1 month and everyone wants xmas presents, especially ruby. :) (2.5.x I suppose) One thing that would be nice is a semi-official tutorial for ruby. We have this in one way or the other here or there, also see Chris Pine nice tutorial ... but I wondered about something more semi-official, a bit like the python tutorial. Martin wrote: > Therefore, I don't think we should pretend that there is one > and only one style by adopting it in core Ruby. Agreed. At the very least not in the way that "there is only one true style and all the others are wrong", since I think that this goes against the philosophy of ruby, or at the least what matz said many years ago (but I think that this is still true and he feels about this in a similar way today). By the way, I am also not 100% happy with yard. It's very good, but it has a few hiccups, e. g. entries such as '# ========== #' which are interpreted oddly... but this is unrelated to core ruby. I just wanted to briefly mention it since it is one tiny problem among, possibly, a few other tiny problems - by and large I am very happy with yard, and I actually started to write most documentation into .md files, which are rendered decently by, I think, kramdown, on rubygems.org gems. The latter is what I tend to use predominantly these days. One can even use ruby badges! :) Here is the ruby badge that I tend to use a lot: https://forthebadge.com/images/badges/made-with-ruby.svg ---------------------------------------- Feature #14112: Follow style conventions for Ruby code https://bugs.ruby-lang.org/issues/14112#change-67834 * Author: ana06 (Ana Maria Martinez Gomez) * Status: Open * Priority: Normal * Assignee: * Target version: ---------------------------------------- The Ruby code in the documentation and in the tests is currently not following any style rules, which leads to long style discussions in PRs as well as making the code more complicate to read and understand. I would really like that Ruby documentation follows [Ruby Style Guide](https://github.com/bbatsov/ruby-style-guide) or equivalently [Rubocop rules](https://github.com/bbatsov/rubocop) as they are driven by the Ruby community and it would be consistent and helpful when developing that Ruby documentation follows it as well. This way we wouldn't need to discuss anything about style in PRs. And when copying code from the documentation you don't have to modify it afterwards. -- https://bugs.ruby-lang.org/ Unsubscribe: