cavalle/the-problem-with-code-examples.md

## the-problem-with-code-examples.md

      
    Raw
  

              the-problem-with-code-examples.md
            
          
    The problem with code examples

Anyone who writes or speaks at conferences about software knows that it's not easy to put together the right code examples. On one side, you want to illustrate just one specific idea or technique, so you try to make your example simple and clear to keep your audience focused. On the other side, if the example is  too simple, chances are that it'll fail to justify your point.
This is an issue I come across often in researching resources about big ActiveRecord models. Let's take this recent post in Victor Savkin's blog. In this writing, the author proposes an alternative way to factor your domain logic in Rails. For that it uses an example which, implemented using a classic Rails way approach, it would have looked like this:
class Order < ActiveRecord::Base
  validates :amount, numericality: true
  has_many :items
end

class Item < ActiveRecord::Base
  validates :amount, numericality: true
  validates :name, presence: true
end
These eight lines of code cover literally all the functionality in the example of the post. If you didn't before, take a close look at the article now. I'll be here when you're done.
The thing is, the snippet above makes the perfect case for the classic way of doing things with ActiveRecord. In comparison, the code in the original example looks ceremonial, full of premature abstractions and unnecessary indirection.
In the rest of the article Savkin makes a good job elaborating on his points. Seemingly, he decided to use words and diagrams to justify his ideas and code just to show how to apply them. That's fair enough I guess, but I don't buy it.
I love good code examples in blog posts and talks. Nothing can be more clarifying and persuasive. Because words are nice but code is the real thing. The ideal code example would be one that shows both how to use a technique and why to use it. This is something hard to achieve and sometimes you have to favour one over the other. In those cases, if I can choose, I prefer you try to show me the why in your code examples.
Further reading

In Avdi Grimm's ebook “Object on Rails” you'll find the most extreme case I've seen of code examples not even remotely trying to justify the techniques they demonstrate. But again, to be fair we must acknowledge that this is completely intentional, as the author explains at the beginning of the book:

…many of the techniques I demonstrate may seem like massive overkill for the task at hand.

Just for reference, this is how the app/models directory of the “task at hand” would look like had we avoided every one of the ideas presented in the book.