Feature #14112: Follow style conventions for Ruby code

• Status: Rejected
• Assignee: -
• Target version: -

[ana06 (Ana Maria Martinez Gomez)]

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 or equivalently Rubocop rules 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.

[duerst (Martin Dürst)]

ana06 (Ana Maria Martinez Gomez) wrote:

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

Can you give some pointers? Please note that Pull Requests (github) are not really part of the core discussion about Ruby, which happens here (bugs.ruby-lang.org). And while I have followed it closely, and there are lots of long discussions, I don't remember any discussions about style issues.

Also, at the monthly Ruby committer meetings here in Japan, style isn't an issue at all; we wouldn't want to spend much time on it because we are busy with other, more important, things.

as well as making the code more complicate to read and understand.

Again, please give some example(s). There are often more than one reason for code to be difficult to understand, and usually the first is that it's a complex subject matter.

I would really like that Ruby documentation follows Ruby Style Guide or equivalently Rubocop rules as they are driven by the Ruby community and it would be consistent and helpful when developing that Ruby documentation follows it as well.

I very much understand when some companies want to have an uniform style. But I have looked at the "Ruby Style Guide", and 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 (except that the rules they like and not might be different :-().

In many cases, there is not a single way of writing Ruby, and that's part of Ruby's culture. (Some other programming languages might handle this differently, as part of their culture.) Therefore, I don't think we should pretend that there is one and only one style by adopting it in core Ruby.

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.

My guess is that you always have to modify code from the documentation anyway, because you are using it just as an example. Adjusting the formatting to your own preferred style will just be a part of it, and is most probably aided by support from your editor (automatic indenting,...).

[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 (by default; you can change this of course, but
I refer to the "main style guide" here) - but the ruby parser allows you to have a lot
more freedom in how YOU want to write ruby code. Yes, other people may not always write
the "cleanest" code and what not, but you have the same situation applied in reverse.
Other people may dislike your code too. This is what comes with diversity - both
advantages and disadvantages.

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). I can happily use ruby without
HAVING to use everything. It also does not bother me greatly either - I can just
focus on code that I write, and ignore the rest. :)

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

[ana06 (Ana Maria Martinez Gomez)]

@duerst (Martin Dürst)

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

Can you give some pointers? Please note that Pull Requests (github) are not really part of the core discussion about Ruby, which happens here (bugs.ruby-lang.org). And while I have followed it closely, and there are lots of long discussions, I don't remember any discussions about style issues.

For example: https://github.com/ruby/ruby/pull/1752#discussion_r151213932 Maybe it is not such a long discussion, but still is making to waste time.

Also, at the monthly Ruby committer meetings here in Japan, style isn't an issue at all; we wouldn't want to spend much time on it because we are busy with other, more important, things.

I do not doubt that you have important things to do, but style is important as well. The probe of it is the amount of people using Rubocop in their projects. It would be such an issue to use Rubocop default configuration in the Ruby code written in the project, and it is really painful reading a documentation which no style conventions. And if you copy something from the documentation you have to modify it afterwards to follow style conventions.

Are this meetings in Japan closed? I mean, are they recorded or is something written down after the meetings that everybody can read it?

as well as making the code more complicate to read and understand.

Again, please give some example(s). There are often more than one reason for code to be difficult to understand, and usually the first is that it's a complex subject matter.

Sure. From the Array documentation:

a = Array.new(2, Hash.new)
Array.[]( 1, 'a', /^A/ )
[ 1, 'a', /^A/ ]
a = [ "a", "a", "b", "b", "c" ]
arr = [1, 2, 3, 4, 5, 6]
a = [ 4, 5, 6 ]

It is not difficult to understand, but it hurts my eyes! Every time you see different syntax or more spaces for the same things you need to identify that it is the same thing. And those are the first examples I found, that I quite simple

I would really like that Ruby documentation follows Ruby Style Guide or equivalently Rubocop rules as they are driven by the Ruby community and it would be consistent and helpful when developing that Ruby documentation follows it as well.

I very much understand when some companies want to have an uniform style. But I have looked at the "Ruby Style Guide", and 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 (except that the rules they like and not might be different :-().

The good of community maintained projects is that everybody can raise their concerns there. Maybe you can raise your concerns there too. And if most people like it, then I think it is enough reason to follow it in the official documentation.

In many cases, there is not a single way of writing Ruby, and that's part of Ruby's culture. (Some other programming languages might handle this differently, as part of their culture.) Therefore, I don't think we should pretend that there is one and only one style by adopting it in core Ruby.

Is the first time that I heard that no having style conventions is part of Ruby's culture. Where is that said?

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.

My guess is that you always have to modify code from the documentation anyway, because you are using it just as an example. Adjusting the formatting to your own preferred style will just be a part of it, and is most probably aided by support from your editor (automatic indenting,...).

Still would be nice to make this job easier.

[ana06 (Ana Maria Martinez Gomez)]

@shevegen (Robert A. Heiler)

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.

@matz (Yukihiro Matsumoto) and what happens with the people reading the code? They may be different to the people writing the code.

Ruby claims to be natural to read and focus on simplicity and productivity. Do you really think that mixing in the code several ways to write the same encourage this principles?

In particular this is my biggest problem with the style guide that is used by rubocop.
Rubocop enforces ONE particular style (by default; you can change this of course, but
I refer to the "main style guide" here) - but the ruby parser allows you to have a lot
more freedom in how YOU want to write ruby code. Yes, other people may not always write
the "cleanest" code and what not, but you have the same situation applied in reverse.
Other people may dislike your code too. This is what comes with diversity - both
advantages and disadvantages.

Rubocop is community maintained. I think that the fact that many Ruby developers are using Rubocop should also be taken into account.

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). I can happily use ruby without
HAVING to use everything. It also does not bother me greatly either - I can just
focus on code that I write, and ignore the rest. :)

But you may find things you don't use in other people code, which you may have to work with.

[stomar (Marcus Stollsteimer)]

ana06 (Ana Maria Martinez Gomez) wrote:

which leads to long style discussions in PRs

Please let's be fair: the "long discussion" that triggered this issue (https://github.com/ruby/ruby/pull/1752#discussion_r151213932) consists essentially of 2 (!) comments from me and one from you (not even very controversial). Calling this a "long discussion" and a waste of time seems a bit strong.

Actually, from what I observe since I follow the issues and PRs, long style discussions (or even any style discussions) do not happen. One reason simply is that documentation PRs are rather scarce, and typically they only fix some typo or add an example.

However, personally I would welcome some basic guidelines, both for Ruby example code and the used RDoc (like e.g. the markup of method arguments). What I currently usually do when improving docs is looking through the affected file or class/module, and use a style similar to the already existing documentation... which is a bit inconvenient. Yet I respect that different maintainers might have different opinions about style, and that there is more than one (good) way to do it. I suppose that most contributors would agree on a major part of the mentioned Ruby style guide rules, anyway; enforcing every single aspect of it with a tool like Rubocop would go too far IMO.

[duerst (Martin Dürst)]

ana06 (Ana Maria Martinez Gomez) wrote:

@duerst (Martin Dürst)

Also, at the monthly Ruby committer meetings here in Japan, style isn't an issue at all; we wouldn't want to spend much time on it because we are busy with other, more important, things.

Are this meetings in Japan closed? I mean, are they recorded or is something written down after the meetings that everybody can read it?

https://bugs.ruby-lang.org/projects/ruby/wiki/Main#Developer-Meetings. There are minutes, but they vary in detail. The meetings are not closed, but they are highly technical, and mostly in Japanese.

Again, please give some example(s). There are often more than one reason for code to be difficult to understand, and usually the first is that it's a complex subject matter.

Sure. From the Array documentation:

a = Array.new(2, Hash.new)

If you carefully study this example (and the text before and after), you will understand that it's written that way on purpose.

Array.[]( 1, 'a', /^A/ )

That's documenting that specific method. I have never used this method (as far as I can remember), and you don't have to if you don't want to, but because the method exists, it should better be documented.

[ 1, 'a', /^A/ ]

That's documenting the literal array notation. If you didn't understand why these different notations are used in the documentation, then please read the documentation more carefully.

a = [ "a", "a", "b", "b", "c" ]
arr = [1, 2, 3, 4, 5, 6]
a = [ 4, 5, 6 ]

The variation between a and arr (and ary) could indeed be removed. But then we might get some people wondering whether variables for arrays always have to be named ary.

It is not difficult to understand, but it hurts my eyes! Every time you see different syntax or more spaces for the same things you need to identify that it is the same thing.

In most present-day programming languages, whitespace can be used (or not used) quite freely. In some way, Ruby is actually an exception, because sometimes, whitespace is not allowed.

The good of community maintained projects is that everybody can raise their concerns there. Maybe you can raise your concerns there too. And if most people like it, then I think it is enough reason to follow it in the official documentation.

Rubocop is a project maintained by the rubocop community. Ruby is a project maintained by the Ruby community. While all people in the rubocop community are also part of the (wider) Ruby community, not everybody in the Ruby community is also in the rubocop community. And even for people in the rubocop community, there are many who use rubocop, but with different settings. So even if we decided to adopt rubocop for Ruby documentation, we would still have to decide which settings to use.

In many cases, there is not a single way of writing Ruby, and that's part of Ruby's culture. (Some other programming languages might handle this differently, as part of their culture.) Therefore, I don't think we should pretend that there is one and only one style by adopting it in core Ruby.

Is the first time that I heard that no having style conventions is part of Ruby's culture. Where is that said?

Not having a single way of writing Ruby, and having no style conventions are not the same. First, "way" can include other issues than just style, e.g. different methods,... Second, not having a single way doesn't mean "everything goes", but it allows for some variability.

[avit (Andrew Vit)]

Some elements of ruby style are hard to check statically because they encode semantics.

For example, I prefer to write blocks using Weirich Braces: this feels less arbitrary than changing syntax for single vs. multi-line blocks. (See Avdi's blog for a deeper discussion.)

Another semantic convention is to use parentheses for "query" methods, but omit them for "command" methods... Again, this choice is part of ruby's expressiveness.

I would not want the documentation to hide the fact that ruby allows method calls without parentheses, just because the default Rubocop style says to use them, or based on a list of arbitrary rules. (What counts as an "internal DSL" or "keyword status" exactly?)

I prefer consistent style too, but instead of enforcing a static syntax check to accomplish this, would it be more helpful to have some plain-language guide for documenters to follow? Or, are the basic things everyone agrees on, like "use two spaces to indent" already listed somewhere?

[stomar (Marcus Stollsteimer)]

I'm only aware of a very brief style guide by the now abandoned Ruby Documentation Project, see http://documenting-ruby.org/documentation-guidelines.html. It doesn't cover Ruby code at all, though, only a bit of RDoc and some general points.

[ana06 (Ana Maria Martinez Gomez)]

ok, it is strange for me to read a documentation with different sintaxis, but it seems that it wouldn't be easy to agree on an style and that a lot of people don't have a problem with this. So, the discussion won't take us anywhere, let's close the issue then!

I think I can not close it, can I?

[hsbt (Hiroshi SHIBATA)]

• Status changed from Open to Rejected