rubocop / ruby-style-guide

= Ruby Style Guide :idprefix: :idseparator: - :sectanchors: :sectlinks: :toc: preamble :toclevels: 1 ifndef::backend-pdf[] :toc-title: pass:[ Table of Contents ] endif::[] :source-highlighter: rouge == Introduction [quote, Officer Alex J. Murphy / RoboCop] ____ Role models are important. ____ ifdef::env-github[] TIP: You can find a beautiful version of this guide with much improved navigation at https://rubystyle.guide. endif::[] This Ruby style guide recommends best practices so that real-world Ruby programmers can write code that can be maintained by other real-world Ruby programmers. A style guide that reflects real-world usage gets used, while a style guide that holds to an ideal that has been rejected by the people it is supposed to help risks not getting used at all - no matter how good it is. The guide is separated into several sections of related guidelines. We've tried to add the rationale behind the guidelines (if it's omitted we've assumed it's pretty obvious). We didn't come up with all the guidelines out of nowhere - they are mostly based on the professional experience of the editors, feedback and suggestions from members of the Ruby community and various highly regarded Ruby programming resources, such as https://pragprog.com/book/ruby4/programming-ruby-1-9-2-0["Programming Ruby"] and https://www.amazon.com/Ruby-Programming-Language-David-Flanagan/dp/0596516177["The Ruby Programming Language"]. This style guide evolves over time as additional conventions are identified and past conventions are rendered obsolete by changes in Ruby itself. ifdef::env-github[] You can generate a PDF copy of this guide using https://asciidoctor.org/docs/asciidoctor-pdf/[AsciiDoctor PDF], and an HTML copy https://asciidoctor.org/docs/convert-documents/#converting-a-document-to-html[with] https://asciidoctor.org/#installation[AsciiDoctor] using the following commands: [source,console] ---- Generates README.pdf asciidoctor-pdf -a allow-uri-read README.adoc Generates README.html asciidoctor README.adoc ---- [TIP] ==== Install the gem to get nice syntax highlighting in the generated document. [source,console] ---- gem install rouge ---- ==== endif::[] [TIP] ==== If you're into Rails or RSpec you might want to check out the complementary https://github.com/rubocop/rails-style-guide[Ruby on Rails Style Guide] and https://github.com/rubocop/rspec-style-guide[RSpec Style Guide]. ==== TIP: https://github.com/rubocop/rubocop[RuboCop] is a static code analyzer (linter) and formatter, based on this style guide. === Guiding Principles [quote, Harold Abelson, Structure and Interpretation of Computer Programs] ____ Programs must be written for people to read, and only incidentally for machines to execute. ____ It's common knowledge that code is read much more often than it is written. The guidelines provided here are intended to improve the readability of code and make it consistent across the wide spectrum of Ruby code. They are also meant to reflect real-world usage of Ruby instead of a random ideal. When we had to choose between a very established practice and a subjectively better alternative we've opted to recommend the established practice.footnote:[Occasionally we might suggest to the reader to consider some alternatives, though.] There are some areas in which there is no clear consensus in the Ruby community regarding a particular style (like string literal quoting, spacing inside hash literals, dot position in multi-line method chaining, etc.). In such scenarios all popular styles are acknowledged and it's up to you to pick one and apply it consistently. Ruby had existed for over 15 years by the time the guide was created, and the language's flexibility and lack of common standards have contributed to the creation of numerous styles for just about everything. Rallying people around the cause of community standards took a lot of time and energy, and we still have a lot of ground to cover. Ruby is famously optimized for programmer happiness. We'd like to believe that this guide is going to help you optimize for maximum programmer happiness. === A Note about Consistency [quote, Ralph Waldo Emerson] ____ A foolish consistency is the hobgoblin of little minds, adored by little statesmen and philosophers and divines. ____ A style guide is about consistency. Consistency with this style guide is important. Consistency within a project is more important. Consistency within one class or method is the most important. However, know when to be inconsistent -- sometimes style guide recommendations just aren't applicable. When in doubt, use your best judgment. Look at other examples and decide what looks best. And don't hesitate to ask! In particular: do not break backwards compatibility just to comply with this guide! Some other good reasons to ignore a particular guideline: • When applying the guideline would make the code less readable, even for someone who is used to reading code that follows this style guide. • To be consistent with surrounding code that also breaks it (maybe for historic reasons) -- although this is also an opportunity to clean up someone else's mess (in true XP style). • Because the code in question predates the introduction of the guideline and there is no other reason to be modifying that code. • When the code needs to remain compatible with older versions of Ruby that don't support the feature recommended by the style guide. === Translations Translations of the guide are available in the following languages: • https://github.com/JuanitoFatas/ruby-style-guide/blob/master/README-zhCN.md[Chinese Simplified] • https://github.com/JuanitoFatas/ruby-style-guide/blob/master/README-zhTW.md[Chinese Traditional] • https://github.com/HassanTC/ruby-style-guide/blob/master/README-EgAr.md[Egyptian Arabic] • https://github.com/gauthier-delacroix/ruby-style-guide/blob/master/README-frFR.md[French] • https://github.com/fortissimo1997/ruby-style-guide/blob/japanese/README.ja.md[Ja…