|
3 | 3 | > Role models are important. <br/> |
4 | 4 | > -- Officer Alex J. Murphy / RoboCop |
5 | 5 |
|
6 | | -One thing has always bothered me as a Ruby developer - Python developers |
7 | | -have a great programming style reference |
8 | | -([PEP-8](http://www.python.org/dev/peps/pep-0008/)) and we never got |
9 | | -an official guide, documenting Ruby coding style and best |
10 | | -practices. And I do believe that style matters. I also believe that a |
11 | | -great hacker community, such as Ruby has, should be quite capable of |
12 | | -producing this coveted document. |
| 6 | +One thing has always bothered me as a Ruby developer - Python developers have a |
| 7 | +great programming style reference |
| 8 | +([PEP-8](http://www.python.org/dev/peps/pep-0008/)) and we never got an official |
| 9 | +guide, documenting Ruby coding style and best practices. And I do believe that |
| 10 | +style matters. I also believe that a great hacker community, such as Ruby has, |
| 11 | +should be quite capable of producing this coveted document. |
13 | 12 |
|
14 | 13 | This guide started its life as our internal company Ruby coding guidelines |
15 | | -(written by yours truly). At some point I decided that the work I was |
16 | | -doing might be interesting to members of the Ruby community in general |
17 | | -and that the world had little need for another internal company |
18 | | -guideline. But the world could certainly benefit from a |
19 | | -community-driven and community-sanctioned set of practices, idioms and |
20 | | -style prescriptions for Ruby programming. |
21 | | - |
22 | | -Since the inception of the guide I've received a lot of feedback from |
23 | | -members of the exceptional Ruby community around the world. Thanks for |
24 | | -all the suggestions and the support! Together we can make a resource |
25 | | -beneficial to each and every Ruby developer out there. |
26 | | - |
27 | | -By the way, if you're into Rails you might want to check out the |
28 | | -complementary |
| 14 | +(written by yours truly). At some point I decided that the work I was doing |
| 15 | +might be interesting to members of the Ruby community in general and that the |
| 16 | +world had little need for another internal company guideline. But the world |
| 17 | +could certainly benefit from a community-driven and community-sanctioned set of |
| 18 | +practices, idioms and style prescriptions for Ruby programming. |
| 19 | + |
| 20 | +Since the inception of the guide I've received a lot of feedback from members of |
| 21 | +the exceptional Ruby community around the world. Thanks for all the suggestions |
| 22 | +and the support! Together we can make a resource beneficial to each and every |
| 23 | +Ruby developer out there. |
| 24 | + |
| 25 | +By the way, if you're into Rails you might want to check out the complementary |
29 | 26 | [Ruby on Rails 3 & 4 Style Guide](https://github.com/bbatsov/rails-style-guide). |
30 | 27 |
|
31 | 28 | # The Ruby Style Guide |
32 | 29 |
|
33 | 30 | This Ruby style guide recommends best practices so that real-world Ruby |
34 | 31 | programmers can write code that can be maintained by other real-world Ruby |
35 | | -programmers. A style guide that reflects real-world usage gets used, and a |
36 | | -style guide that holds to an ideal that has been rejected by the people it is |
37 | | -supposed to help risks not getting used at all – no matter how good it is. |
38 | | - |
39 | | -The guide is separated into several sections of related rules. I've |
40 | | -tried to add the rationale behind the rules (if it's omitted I've |
41 | | -assumed it's pretty obvious). |
42 | | - |
43 | | -I didn't come up with all the rules out of nowhere - they are mostly |
44 | | -based on my extensive career as a professional software engineer, |
45 | | -feedback and suggestions from members of the Ruby community and |
46 | | -various highly regarded Ruby programming resources, such as |
47 | | -["Programming Ruby 1.9"](http://pragprog.com/book/ruby4/programming-ruby-1-9-2-0) |
48 | | -and ["The Ruby Programming Language"](http://www.amazon.com/Ruby-Programming-Language-David-Flanagan/dp/0596516177). |
49 | | - |
50 | | -There are some areas in which there is no clear consensus in the |
51 | | -Ruby community regarding a particular style (like string literal quoting, |
52 | | -spacing inside hash literals, dot position in multi-line method |
53 | | -chaining, etc.). In such scenarios all popular styles are acknowledged |
54 | | -and it's up to you to pick one and apply it consistently. |
55 | | - |
56 | | -The guide is still a work in progress - some rules are lacking |
57 | | -examples, some rules don't have examples that illustrate them clearly |
58 | | -enough. In due time these issues will be addressed - just keep them in |
59 | | -mind for now. |
| 32 | +programmers. A style guide that reflects real-world usage gets used, and a style |
| 33 | +guide that holds to an ideal that has been rejected by the people it is supposed |
| 34 | +to help risks not getting used at all – no matter how good it is. |
| 35 | + |
| 36 | +The guide is separated into several sections of related rules. I've tried to add |
| 37 | +the rationale behind the rules (if it's omitted I've assumed it's pretty |
| 38 | +obvious). |
| 39 | + |
| 40 | +I didn't come up with all the rules out of nowhere - they are mostly based on my |
| 41 | +extensive career as a professional software engineer, feedback and suggestions |
| 42 | +from members of the Ruby community and various highly regarded Ruby programming |
| 43 | +resources, such as ["Programming Ruby |
| 44 | +1.9"](http://pragprog.com/book/ruby4/programming-ruby-1-9-2-0) and ["The Ruby |
| 45 | +Programming |
| 46 | +Language"](http://www.amazon.com/Ruby-Programming-Language-David-Flanagan/dp/0596516177). |
| 47 | + |
| 48 | +There are some areas in which there is no clear consensus in the Ruby community |
| 49 | +regarding a particular style (like string literal quoting, spacing inside hash |
| 50 | +literals, dot position in multi-line method chaining, etc.). In such scenarios |
| 51 | +all popular styles are acknowledged and it's up to you to pick one and apply it |
| 52 | +consistently. |
| 53 | + |
| 54 | +The guide is still a work in progress - some rules are lacking examples, some |
| 55 | +rules don't have examples that illustrate them clearly enough. In due time these |
| 56 | +issues will be addressed - just keep them in mind for now. |
60 | 57 |
|
61 | 58 | You can generate a PDF or an HTML copy of this guide using |
62 | 59 | [Transmuter](https://github.com/TechnoGate/transmuter). |
63 | 60 |
|
64 | | -[RuboCop](https://github.com/bbatsov/rubocop) is a code analyzer, |
65 | | -based on this style guide. |
| 61 | +[RuboCop](https://github.com/bbatsov/rubocop) is a code analyzer, based on this |
| 62 | +style guide. |
66 | 63 |
|
67 | 64 | Translations of the guide are available in the following languages: |
68 | 65 |
|
|
0 commit comments