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: <mailto:ruby-core-request / ruby-lang.org?subject=unsubscribe>
<http://lists.ruby-lang.org/cgi-bin/mailman/options/ruby-core>