Last active

Embed URL

HTTPS clone URL

SSH clone URL

You can clone with HTTPS or SSH.

Download Gist

The problem with code examples

View 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.

I agree with your article in full. All too often I have seen great developers make simple concepts multitudes more complex than necessary in order to fulfill some ideological coding belief. To be fair to Savkin did give 5 bullet points to the 'why'...unfortunately, 3 of 5 reasons were related to test performance, not an actual feature problem. The other 2 reasons were that active record instances having "too much power, and as we all know, it corrupts."....I don't even know what that is supposed to mean. Thanks for KISS'ing and pointing out why it still should rein supreme in the dev world!

An interesting writeup. In that post Savkin suggests the 'why' is not making your business logic tied to Rails. Thus leading to better testability. I like the idea but since Rails isn't ready for it, I think it is difficult to follow in practice.

This is an issue I come across often in researching resources about big ActiveRecord models.

Big models would make his code example very much harder to follow. Did you really want a 5000 line God Object to demonstrate why big models are a problem? Of course the diddy example models would be more concise if written in a classic rails style. But his approach isn't intended for small models like the examples.

KISS just isn't a viable options for some apps. Clearly defined responsibilities is a great way of tackling complexity when it occurs, and Rails doesn't exactly encourage that. Not that it matters for 90% of Rails apps anyway. I welcome Victor's approach and may well adopt it if and when I need it. Until I do, AR will do just fine.

I'm trying to strike the balance between the why and the examples. I think I'm getting better at it: http://blog.markstarkman.com/blog/2013/02/06/rspec-shared-examples-and-ruby-metaprogramming/

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Something went wrong with that request. Please try again.