Issue #14112 has been updated by 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][1]: this feels less arbitrary than changing syntax for single vs. multi-line blocks. (See [Avdi's blog][2] 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][3]. (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?

[1]: http://archive.is/96ko8
[2]: http://www.virtuouscode.com/2011/07/26/the-procedurefunction-block-convention-in-ruby/
[3]: https://github.com/bbatsov/ruby-style-guide#method-invocation-parens

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

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