Prelude Role models are important. – Officer Alex J. Murphy / RoboCop One thing h

Prelude Role models are important. – Officer Alex J. Murphy / RoboCop One thing has always bothered me as Ruby developer - Python developers have a great programming style reference (PEP-8) and we never got an official guide, documenting Ruby coding style and best practices. And I do believe that style matters. I also believe that a great hacker community, such as Ruby has, should be quite capable of producing this coveted document. This guide started its life as our internal company Ruby coding guidelines (writ- ten by yours truly). At some point I decided that the work I was doing might be interesting to members of the Ruby community in general and that the world had little need for another internal company guideline. But the world could certainly benefit from a community-driven and community-sanctioned set of practices, idioms and style prescriptions for Ruby programming. Since the inception of the guide I’ve received a lot of feedback from members of the exceptional Ruby community around the world. Thanks for all the sugges- tions and the support! Together we can make a resource beneficial to each and every Ruby developer out there. By the way, if you’re into Rails you might want to check out the complementary Ruby on Rails 3 Style Guide. The Ruby Style Guide This Ruby style guide recommends best practices so that real-world Ruby pro- grammers can write code that can be maintained by other real-world Ruby programmers. A style guide that reflects real-world usage gets used, and 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 rules. I’ve tried to add the rationale behind the rules (if it’s omitted I’ve assumed that is pretty obvious). I didn’t come up with all the rules out of nowhere - they are mostly based on my extensive career as a professional software engineer, feedback and sugges- tions from members of the Ruby community and various highly regarded Ruby programming resources, such as “Programming Ruby 1.9” and “The Ruby Pro- gramming Language”. The guide is still a work in progress - some rules are lacking examples, some rules don’t have examples that illustrate them clearly enough. In due time these issues will be addressed - just keep them in mind for now. You can generate a PDF or an HTML copy of this guide using Transmuter. 1 RuboCop is a code analyzer, based on this style guide. Translations of the guide are available in the following languages: • Chinese Simplified • Chinese Traditional • French Table of Contents • Source Code Layout • Syntax • Naming • Comments – Comment Annotations • Classes • Exceptions • Collections • Strings • Regular Expressions • Percent Literals • Metaprogramming • Misc • Tools Source Code Layout Nearly everybody is convinced that every style but their own is ugly and unreadable. Leave out the “but their own” and they’re probably right. . . – Jerry Coffin (on indentation) • Use UTF-8 as the source file encoding. • Use two spaces per indentation level. No hard tabs. 2 # bad - four spaces def some_method do_something end # good def some_method do_something end • Use Unix-style line endings. (*BSD/Solaris/Linux/OSX users are covered by default, Windows users have to be extra careful.) – If you’re using Git you might want to add the following configuration setting to protect your project from Windows line endings creeping in: $ git config –global core.autocrlf true • Don’t use ; to separate statements and expressions. As a corollary - use one expression per line. # bad puts ’foobar’; # superfluous semicolon puts ’foo’; puts ’bar’ # two expression on the same line # good puts ’foobar’ puts ’foo’ puts ’bar’ puts ’foo’, ’bar’ # this applies to puts in particular • Prefer a single-line format for class definitions with no body. # bad class FooError < StandardError end # okish class FooError < StandardError; end # good FooError = Class.new(StandardError) • Avoid single-line methods. Although they are somewhat popular in the wild, there are a few peculiarities about their definition syntax that make 3 their use undesirable. At any rate - there should be no more than one expression in a single-line method. # bad def too_much; something; something_else; end # okish - notice that the first ; is required def no_braces_method; body end # okish - notice that the second ; is optional def no_braces_method; body; end # okish - valid syntax, but no ; make it kind of hard to read def some_method() body end # good def some_method body end One exception to the rule are empty-body methods. # good def no_op; end • Use spaces around operators, after commas, colons and semicolons, around { and before }. Whitespace might be (mostly) irrelevant to the Ruby interpreter, but its proper use is the key to writing easily readable code. sum = 1 + 2 a, b = 1, 2 1 > 2 ? true : false; puts ’Hi’ [1, 2, 3].each { |e| puts e } The only exception, regarding operators, is the exponent operator: # bad e = M * c ** 2 # good e = M * c**2 { and } deserve a bit of clarification, since they are used for block and hash literals, as well as embedded expressions in strings. For hash literals two styles are considered acceptable. 4 # good - space after { and before } { one: 1, two: 2 } # good - no space after { and before } {one: 1, two: 2} The first variant is slightly more readable (and arguably more popular in the Ruby community in general). The second variant has the advantage of adding visual difference between block and hash literals. Whichever one you pick - apply it consistently. As far as embedded expressions go, there are also two acceptable options: # good - no spaces "string#{expr}" # ok - arguably more readable "string#{ expr }" The first style is extremely more popular and you’re generally advised to stick with it. The second, on the other hand, is (arguably) a bit more readable. As with hashes - pick one style and apply it consistently. • No spaces after (, [ or before ], ). some(arg).other [1, 2, 3].length • Indent when as deep as case. I know that many would disagree with this one, but it’s the style established in both “The Ruby Programming Language” and “Programming Ruby”. case when song.name == ’Misty’ puts ’Not again!’ when song.duration > 120 puts ’Too long!’ when Time.now.hour > 21 puts "It’s too late" else song.play end kind = case year when 1850..1889 then ’Blues’ when 1890..1909 then ’Ragtime’ when 1910..1929 then ’New Orleans Jazz’ when 1930..1939 then ’Swing’ 5 when 1940..1950 then ’Bebop’ else ’Jazz’ end • Use empty lines between defs and to break up a method into logical paragraphs. def some_method data = initialize(options) data.manipulate! data.result end def some_method result end • Use spaces around the = operator when assigning default values to method parameters: # bad def some_method(arg1=:default, arg2=nil, arg3=[]) # do something... end # good def some_method(arg1 = :default, arg2 = nil, arg3 = []) # do something... end While several Ruby books suggest the first style, the second is much more prominent in practice (and arguably a bit more readable). • Avoid line continuation \ where not required. In practice, avoid using line continuations at all. # bad result = 1 - \ 2 # good (but still ugly as hell) result = 1 \ - 2 • When continuing a chained method invocation on another line keep the . on the second line. 6 # bad - need to consult first line to understand second line one.two.three. four # good - it’s immediately clear what’s going on the second line one.two.three .four • Align the parameters of a method call if they span more than one line. When aligning parameters is not appropriate due to line-length constraints, single indent for the lines after the first is also acceptable. # starting point (line is too long) def send_mail(source) Mailer.deliver(to: ’bob@example.com’, from: ’us@example.com’, subject: ’Important mes end # bad (double indent) def send_mail(source) Mailer.deliver( to: ’bob@example.com’, from: ’us@example.com’, subject: ’Important message’, body: source.text) end # good def send_mail(source) Mailer.deliver(to: ’bob@example.com’, from: ’us@example.com’, subject: ’Important message’, body: source.text) end # good (normal indent) def send_mail(source) Mailer.deliver( to: ’bob@example.com’, from: ’us@example.com’, subject: ’Important message’, body: source.text ) end • Add underscores to large numeric literals to improve their readability. 7 # bad - how many 0s are there? num = 1000000 # good - much easier to parse for the human brain num = 1_000_000 • Use RDoc and its conventions for API documentation. Don’t put an empty line between the comment block and the def. • Limit lines to 80 characters. • Avoid trailing whitespace. • Don’t use uploads/s3/ ruby-style-guide.pdf

Tags
Administrationclass avoid method rescue omitted
Documents similaires
  • 33
  • 0
  • 0
Afficher les détails des licences
Licence et utilisation
Gratuit pour un usage personnel Attribution requise
Partager