Avoid the need for comments

As comments are not executable, they are easily out of date. They are a form of decaying documentation.

If the code inside a method needs a comment, you probably can extract the code into a new method whose name explains what you need to clarify.

Moreover, the Single Responsibility Principle says that classes and methods should have a single responsibility so when you need comments they probably have more than one responsibility.

Therefore instead of:

def gear_inches
  # tire goes around rim twice for diameter
  ratio * rim + (tire * 2)
end

The following is clearer and needs no comment:


def gear_inches
  ratio * diameter
end

def diameter
  rim + (tire * 2)
end

Examples from POODR and here.


Practical Object-Oriented Design in Ruby

This book is great:
http://www.poodr.com
POODR


Vim & Tmux video


Duplication is far cheaper than the wrong abstraction

Sandy Metz said that if you find yourself passing parameters and adding conditional paths through shared code, the abstraction is incorrect. Then you should go back:

  1. Re-introduce duplication by inlining the abstracted code back into every caller.
  2. Within each caller, examine the parameters that got passed in order figure out which bits of the inlined code you actually use.
  3. Delete the bits that aren’t needed for this particular caller.

Null Object Pattern

Bad:

ids = ['pig', '', 'sheep']

animals = ids.map {|id| Animal.find(id)}

animals.each do |animal|
  puts animal.nil? ? 'no animal' : animal.name
end

Good:

animals = ids.map{ |id| GuaranteedAnimal.find(id) }
animals.each{ |animal| puts animal.name }

class GuaranteedAnimal
  def self.find(id)
    Animal.find(id) || MissingAnimal.new
  end
end

class MissingAnimal
  def name
    'no animal'
  end
end

Seen in the video of Sandi Metz in RailsConf 2015:


Wikidata

wikidata-logoWikidata is the Wikipedia project for structured knowledge. For example it knows that the capital of Spain is Madrid. The ruby gem wikidata has a basic support to retrieve it:


require 'wikidata'

Wikidata::Item.find_by_title('Spain').claims_for_property_id('P36').first.mainsnak.value.entity.label