Issue #14112 has been updated by duerst (Martin Drst).


ana06 (Ana Maria Martinez Gomez) wrote:
> @duerst 

> > 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:
> 
> ``` Ruby
> 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.

> ``` Ruby
> 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.

> ``` Ruby
> [ 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.


----------------------------------------
Feature #14112: Follow style conventions for Ruby code
https://bugs.ruby-lang.org/issues/14112#change-67853

* 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>