Issue #14112 has been updated by ana06 (Ana Maria Martinez Gomez).


@duerst 

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

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

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

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