Slides of my talk at Rubyconf India 2013

1. Write your
- by
Bhavin Javia
@bhavinjavia
in
Style
www.mavenhive.in

2. Who this talk is
NOT for ?

3. I am the only one !

4. Who this talk
IS for ?

5. Dad ! Who’s ‘Ruby’ ?

6. Teams

7. Open Source
Contributors

8. Style Matters

9. Why bother ?

10. Story

11. Rubo

12. • Fascinated by computers
• Learnt programming in school/college
• Knew a few languages - C, C++, Java
• Loved Ruby
• Joined a Startup as an Intern
• Full of Ruby veterans
• Felt right at home
Story of Rubo

13. Ruby Rocks !

14. But,

15. As soon as he
committed some
code ...

16. WTF ?
OMG !
#$%@ Caveman !

17. Oh, Where did I
go wrong ?!

18. What was wrong ?

19. He lacked Style

20. Masters of Ruby
Style
http://www.flickr.com/photos/jakescruggs/4687409786/
http://vimeo.com/steveklabnik
https://si0.twimg.com/profile_images/2931712744/95043c0f42f0700bdbd713635e942ac0.jpeg
http://peepcode.com/blog/2011/my-avatar/circle1.jpg

21. • Java - Code Conventions for Java (by Oracle)
• Python - Style Guide for Python Code (PEP 8)
• PHP - Basic Coding Standard (PSR-1)
Many languages have
Coding Standards
http://www.oracle.com/technetwork/java/codeconv-138413.html
http://www.python.org/dev/peps/pep-0008/
http://www.php-fig.org/psr/1/

22. Why Ruby doesn’t ?

23. Many ways
to do things ...

24. And all of them work !

25. Ruby Sucks !

26. We need a Style Guide

27. What is a Style Guide ?

28. What’s a Style Guide ?
• Better way to write code
• Better way to lay-out code
• Right idioms to use and when
• Simplicity and Elegance

29. Helps you decide ...

30. http://flic.kr/p/5n8Rrd
what your code should look like ?
this ...

31. http://flic.kr/p/voGgz
or this ?

32. I’ve got my own Style

33. Why Style Guide ?

34. Why Style Guide ?
• Functional correctness not enough
• Visual consistency matters
• Reduce cognitive friction
• Avoid religious wars
• Increase team productivity
• Long term maintainability

35. Let the team own it

36. When
no one
owns the code,
everyone
owns the code !

37. http://flic.kr/p/6mHZfT
code which lasts 1000s of years

38. Examples

39. Code Layout

40. “ 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)

41. # encoding: utf-8
https://help.github.com/articles/dealing-with-line-endings
$ git config --global core.autocrlf input # Mac/Linux
$ git config --global core.autocrlf true # Windows
Use UTF-8 as the source file encoding
Use Unix-style line endings

42. # bad - four spaces
def some_method
do_something
end
# good
def some_method
do_something
end
* No tabs please
Two spaces per indent

43. # bad
def too_much; something; something_else; end
# okish
def no_braces_method; body; end
# okish
def some_method() body end
# good
def some_method
body
end
* Not applicable to empty methods e.g.
# good
def no_op; end
Avoid single-line methods

44. # around operators, after commas, colons and semicolons,
around `{` and before `}`
sum = 1 + 2
a, b = 1, 2
1 > 2 ? true : false; puts 'Hi'
[1, 2, 3].each { |e| puts e }
* Not with exponent operator
# bad
e = M * c ** 2
# good
e = M * c**2
Use spaces

45. Indent when as deep as case
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'
when 1940..1950 then 'Bebop'
else 'Jazz'
end

46. Avoid line continuation
# bad
result = 1 -
2
# bad
result = 1
- 2

47. # bad
one.two.three.
four
# good
one.two.three
.four
Chain methods with .

48. Align multi-line params
# starting point (line is too long)
def send_mail(source)
Mailer.deliver(to: 'bob@example.com', from:
'us@example.com', subject:
'Important message', body: source.
text)
end
# bad (normal indent)
def send_mail(source)
Mailer.deliver(
to: 'bob@example.com',
from: 'us@example.com',
subject: 'Important message',
body: source.text)
end

49. Align multi-line params
# 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

50. num = 1000000
num = 1_000_000
Which one is correct ?

51. num = 1000000
num = 1_000_000
Both !
Which one is better ?

52. Add underscores to large
numeric literals
# bad - how many 0s are there?
num = 1000000
# good - much easier to parse
num = 1_000_000

53. class Array
# Calls <tt>to_param</tt> on all its elements and joins the result with
# slashes. This is used by <tt>url_for</tt> in Action Pack.
def to_param
collect { |e| e.to_param }.join '/'
end
end
Use RDoc and its conventions
for API docs

54. Syntax

55. Use Iterators
arr = [1, 2, 3]
# bad
for elem in arr do
puts elem
end
# good
arr.each { |elem| puts elem }

56. # bad
result = if some_condition then something else something_else end
# good
result = some_condition ? something : something_else
* for one line constructs
Favor the ternary operator (?:)
over if/then/else/end

57. # bad
some_condition ? (nested_condition ? nested_something :
nested_something_else) : something_else
# good
if some_condition
nested_condition ? nested_something : nested_something_else
else
something_else
end
Use one expression per branch
in a ternary operator

58. # bad
if
some_condition
do_something
do_something_else
end
# good
if some_condition
do_something
do_something_else
end
Always put the condition on
the same line

59. Favor unless over if for
negative conditions
# bad
do_something if !some_condition
# bad
do_something if not some_condition
# good
do_something unless some_condition
# another good option
some_condition || do_something

60. class Person
attr_reader :name, :age
# omitted
end
temperance = Person.new('Temperance', 30)
temperance.name
puts temperance.age
x = Math.sin(y)
array.delete(e)
bowling.score.should == 0
Omit parentheses around parameters
for methods that are part of internal
DSL, keyword status, accessors

61. names = ['Bozhidar', 'Steve', 'Sarah']
# bad
names.each do |name|
puts name
end
# good
names.each { |name| puts name }
* Avoid using {...} for multi-line blocks
Prefer {...} over do...end for
single-line blocks

62. # bad
def some_method(some_arr)
return some_arr.size
end
# good
def some_method(some_arr)
some_arr.size
end
Avoid return where not
required for flow of control

63. # bad
def ready?
if self.last_reviewed_at > self.last_updated_at
self.worker.update(self.content, self.options)
self.status = :in_progress
end
self.status == :verified
end
# good
def ready?
if last_reviewed_at > last_updated_at
worker.update(content, options)
self.status = :in_progress
end
status == :verified
end
* only required when calling a self write accessor
Avoid self where not required

64. Naming

65. “The only real difficulties in programming are cache
invalidation and naming things.
- Phil Karlton

66. Name identifiers in English
# bad - variable name written in Bulgarian with
latin characters
zaplata = 1_000
# good
salary = 1_000

67. Use CamelCase for
classes and modules
# bad
class Someclass
...
end
class Some_Class
...
end
class SomeXml
...
end
# good
class SomeClass
...
end
class SomeXML
...
end
* Keep acronyms like
HTTP, RFC, XML
uppercase

68. Use snake_case for symbols,
methods and variables
# bad
:'some symbol'
:SomeSymbol
:someSymbol
someVar = 5
def someMethod
...
end
def SomeMethod
...
end
# good
:some_symbol
some_var = 5
def some_method
...
end

69. Use SCREAMING_SNAKE_CASE
for other constants.
# bad
SomeConst = 5
# good
SOME_CONST = 5

70. Predicate methods shouldshould
end in a question mark ‘?’
# bad
def available
appointments.empty?
end
# good
def available?
appointments.empty?
end
* e.g. Array#empty?

71. Comments

72. “ Good code is its own best documentation ...
- Steve McConnell
“ Good code is like a good joke - it needs no explanation.
- Russ Olsen

73. Avoid superfluous comments
# bad
counter += 1 # increments counter by one

74. Avoid writing
comments to explain
bad code

75. An outdated comment
is worse than
no comment at all !

76. DON’T do it !

77. Use Comment
Annotations
• Use TODO to note missing features
• Use FIXME to note broken code
• Use HACK to note code smells
• Use OPTIMIZE to note inefficient code

78. One you’ve added
annotations

79. DO do the TODO !

80. Classes & Modules

81. Use a consistent structure in
your class definitions
class Person
# extend and include
extend SomeModule
include AnotherModule
# constants
SOME_CONSTANT = 20
# attribute macros
attr_reader :name
# other macros (if any)
validates :name
# public class methods are next in line
def self.some_method
end
# followed by public instance methods
def some_method
end
# protected/private methods
end

82. Implement to_s on
domain classes
class Person
attr_reader :first_name, :last_name
def initialize(first_name, last_name)
@first_name = first_name
@last_name = last_name
end
def to_s
"#{@first_name} #{@last_name}"
end
end

83. Use the attr family of functions
to define trivial accessors
# bad
class Person
def initialize(first_name, last_name)
@first_name = first_name
@last_name = last_name
end
def first_name
@first_name
end
def last_name
@last_name
end
end
# good
class Person
attr_reader :first_name, :last_name
def initialize(first_name, last_name)
@first_name = first_name
@last_name = last_name
end
end

84. What if I don’t like these
‘rules’ ?

85. Rules are meant
to be broken !
http://flic.kr/p/dKyXLP

86. http://flic.kr/p/7MdXLX
These are just
guidelines

87. Follow Style Guide
consistently

88. But,

89. “ A Foolish Consistency is the Hobgoblin of Little Minds
- Essays: First Series by RalphWaldo Emerson

90. Consistency at what level ?
• consistency with style guide - important
• consistency with project - more important
• consistency with module - most important
• readability matters

91. https://twitter.com/AgileBorat/status/307791971991289856

92. When to break the rule ?
• Applying the rule makes it less readable
• To be consistent with surrounding code
• Opportunity to clean up the mess

93. How to enforce
these rules ?

94. • Make it a standard team practice
• Select/Draft a style guide for project
• Make it a must read for everyone
• Use IDE support e.g. RubyMine inspections
How to enforce these rules ?

95. • Use Style Checker tools
• Integrate with CI
• Use a live style guide - fork it, send PRs
• Commit your IDE settings
• Point out violations in context
• Use Github inline commit notes
How to enforce these rules ?

96. https://github.com/blog/622-inline-commit-notes

97. Tools

98. Rubocop
https://github.com/bbatsov/rubocop

100. Demo

103. Like a Boss !

104. References
• https://github.com/bbatsov/ruby-style-guide
• https://github.com/styleguide/ruby
• https://github.com/bbatsov/rails-style-guide
Style Guides

105. References
• https://github.com/bbatsov/rubocop
• https://github.com/martinjandrews/roodi
• https://github.com/troessner/reek
Tools

106. Give it a shot

107. YMMV

108. Contribute your Style
to the community

109. ThankYou

110. Questions ?
@bhavinjavia
bhavin@mavenhive.in
www.mavenhive.in
@mavenhive