Clean Code
Keeping your code readable
By: Arnoldo Rodriguez
@arnoldocolin
Giving Meaningful names
Intention revealing
Pronounceable
Distinctable
Class names should be nouns / noun verbs
Method names should be verbs / verb
phrase
One Word per concept
Names: Intention Revealing & Pronounceable
edt
end_date_time
sdt
start_date_time
nme
name
fname
stotal
VS
full_name
subtotal
pgup
page_up
lng
longitud
Names: Distinctable, never duplicate...
info
description
destroy
delete
name
fullname
place
house
process
VS
location
home
execute
Names: Class names should be a...
Noun
User
Form
Friend
Noun phrase
Signup
DiscountCalculator
TripFinder
Names: Method names should be a...
Verb
invite
authorize
validate
Verb Phrase
find_location
has_friendship_with
send_email
Functions should...
be small (do 1 thing, 1 level of abstraction)
never use switch statements
1, 2, 3 arguments, no more!
Do something or answer something
have no side effects
Functions: Do 1 thing & 1 Level of Abstraction
class Order
# Wrong: calculating several things
def total
subtotal = items.sum(:price)
discount = items.sum(:discount)
subtotal - discount
end
end
class Order
# Good. One level of abstraction, One thing
# Remember to declare utility functions just
# below where they are being called
def total
subtotal - discount
end
def subtotal
items.sum(:price)
end
def discount
items.sum(:discount)
end
end
Not OK
Ok!
Functions: Never use switch statements
class Payment
attr_reader payment_method
class Payment
attr_reader payment_method
def process
case payment_method.class
when "CreditCart"
when "Deposit"
when "Cash"
end
end
# A switch statement hides an
# opportunity to use
# polymorphism or duck typing
def process
payment_method.purchase(self)
end
end
Not OK
Ok!
Functions: Zero arguments is the winner!
No arguments to remember
Use instance variables, but remember the cohesion
principle:
All methods (in a class) should use most of the
instance variables in that class
Functions: One argument, Ask? or Transform not both
class User
# This is asking something
def has_friendship_with(another_user)
Friendship.exists?(self, another_user)
end
# This is transforming something
def change_password(new_password)
self.password = new_password
end
end
Functions: Two arguments sucks
Avoid or convert to one argument using
instance variables.
Give functions better names.
# Hard to remember gotta google it bitch!
asserts_equal(expected, actual)
# Easy to remember no need for the api
asserts_expected_to_eq_actual(expected, actual)
Functions: Three arguments, avoid at all costs
If you cant then use:
argument objects
argument lists
# send options hash for a list html options
def text_field_tag(name, value, html_options={})
end
# convert x, y coordinates into a center object
def make_circle(center, radius)
end
Functions: Make sure they have no side effects
# The side effect is sending an email notification
def create_account(attributes={})
account = Account.create(attributes)
send_notification_email(account) unless account.new_record?
end
# We can give the function a better name
# though violates the do 1 thing
# the best solution is to abstract it to a new object signup
def create_account_and_notify(attributes={})
end
Comments are...
Shitz
A pain in the ass to maintain
To be avoided if we follow good design
practices
Exceptions: return exceptions instead of error codes
# Using an error code
def withdraw(amount)
if amount > balance
return -1
else
balance -= amount
end
end
Not OK
# Using an exception, easier coz it give us
#context
def withdraw(amount)
raise BalanceException if amount > balance
balance -= amount
end
Ok!
Unit tests should follow...
3 Laws of TDD
One assert per test
F.I.R.S.T.
Unit Tests: 3 Laws of TDD
First: You may not write production code until you have
written a failing unit test.
Second: You may not write more of a unit test than is
sufficient to fail
Third: You may not write more production code than is
sufficient to pass the currently failing test.
Unit Tests: One assert per test
Use the Given, When, Then to test one
concept per test.
Unit Tests: F.I.R.S.T.
Fast: Tests should be fast.
Independent: Tests should not depend on each other.
Repeatable: Tests should be repeatable in any
environment.
Self-Validating: Test should have a boolean output.
Timely: Unit Tests should be write just before
production code.
Classes should...
Keep variables & utility functions private
Follow the Single Responsibility Principle
Follow the Open-Closed principle
Follow the Dependency inversion Principle
Follow the law of Demeter
Classes: Single Responsibility Principle
# Several responsibilities
class User
attr_accessor first_name, last_name, email
def full_name
"#{first_name} #{last_name}"
end
def send_confirmation_email
end
def recover_password
end
end
# By dividing responsibilities
# we ended up with more objects
class User
attr_accessor first_name, last_name, email
def full_name
"#{first_name} #{last_name}"
end
end
class PasswordRetriever
def retrieve
end
end
class Signup
def sign_up
end
private
def send_confirmation_email
end
end
Not OK
Ok!
Classes: Open-Close Principle
# Everytime we want a new SQL method
# we will have to open and change the class
# clearly violates Open-Close Principle
class SQL
def insert
# codez, codez...
end
# Using inheritance we follow the Open-Close #
Principle
# A class must be Open for extension but
#Close for modification
class SQL
# superclass codez goes here...
end
def select
# codez, codez...
end
end
class Insert < SQL
# specialization codez goes here...
end
class Select < SQL
# specialization codez goes here...
end
Not OK
Ok!
Classes: Dependency Inversion
class Report
# Class dependent, what if we need another format?
def export_pdf
PDFExporter.export(self)
end
# Inverting the dependency, we can use any format now
def export(format = PDFExporter)
format.export(self)
end
end
# Endless possibilities
report = Report.new
report.export(PDFExporter)
report.export(XLSExporter)
report.export(NumbersExporter)
report.export(HTMLExporter)
Classes: Law of Demeter
Method F of class C should only call methods of these
(only use one dot):
C
An object created by F
An object passed as an argument to F
An object held in an instance variable of C
class jockey
# we don't need to tell the paws to move
def run_horse
horse.paws.move(speed: fast)
end
end
Not OK
class jockey
# use only one dot!
def run_horse
horse.run
end
end
Ok!
A simple design is one that...
Runs all tests
Has no duplication
Expresses intent
Minimizes the number of classes
Refactor (make it work, make it right)
