So, now we came to a point where our app no longer fit to vanilla MVC and we want to extract a service layer. By “Service Layer” I mean a collection of Plain Old Ruby Objects, which hold pure business logic. What kind of POROs it might be? Here’s good examples by Bryan Helmkamp.

But, anyway, the question is – where do we put them in our Rails app files structure?

We got several options here:

1. Dump everything to lib/ dir
2. Call them non-ActiveRecord Models and put them in app/models/
3. Use Cases and Entities (DDD approach). So app/use_cases/ & app/entities/
4. ???

Let’s go through these options one after another.

1. lib/

If class/module is not Model, View or Controller, it suppose to go to lib/, isn’t it? Well, this approach got some disadvantages.

When you start to extract your business logic to POROs, on a big project you’re going to have a few dozen of them, maybe hundred(s). Pretty soon you open your lib/ – and it scares you. Even worse when it gets explored by a new team member.

Another thing – it’s pretty easy to loose track on what is used where and for what reason. Especially in dynamic metaprogramming-friendly language like Ruby.

So, slowly but surely, lib/ becomes “a big ball of mud”.

2. non-ActiveRecord Models

We can say that PORO, which returns data structure(or for whatever other reason), is non-ActiveRecord model and put it in models/

Well, that’s better. Sort of. Part is in lib/, part is in models/. A slightly less mess, but in two places now.

Besides, there’s a problem each time to decide, whether this PORO is a “model” or not. And it’s even harder for others to guess, where to find that class(in models/ or still in lib/), when they explore your code.

3. Use Cases & Entities

The concept of Use Cases & Entities comes from DDD and from Bob Martin’s talk “Architecture: The Lost Years”. So, the core of your system suppose be in UseCases(verbs e.g. CreateUser) and Entities(nouns e.g. User).

But the problem with this – it takes you far away from “The Rails Way”. In one case I want to use my ActiveRecord model as Entitly, but in the other case it should be a separate class with it’s corresponding Repository class. Sometimes, my Controller is pretty much the UseCase, but sometimes I want to extract a few classes from it.

Decisions, decisions. It’s all confusing. Besides, everyone in the team need to share the exact same architectural concepts (which is solved by “The Rails Way” at first place). Pretty quick the codebase can become more mess and hard to follow through, than it was before.

4. Namespaces FTW!

So, there’s another approach, which is used by every single gem and almost any other Ruby program – the namespaced classes and modules.

Disclaimer: As usual, code examples are highly synthetic and short to keep them easy to follow. Your “results may vary”.

Example with Controllers

Let’s say you got a dashboard in your app.

1
2
3
4

class DashboardController < ApplicationController
    def index
    end
end

And you want to show a list of users on this dashboard. But user list should be paginated, sortable, and current_user-specific. Now, I think it’s a good idea to create a UserList class, which will handle all this logic.

But where do I put this class? Is this a Service / Model / Use Case / Entity / Query Object / Policy Object? When using namespaces, the answer is – I don’t really care.

All I need to do is to create one more folder in controllers/ with the same name as controller.

1
2
3
4

controllers
├── dashboard_controller
│   └── user_list.rb
└── dashboard_controller.rb

and put my UserList class there

1
2
3
4
5
6
7

# app/controllers/dashboard_controller/user_list.rb

class DashboardController
  class UserList
    # codes codes codes
  end
end

and then it can be used in DashboardController like this

1
2
3
4
5
6
7
8
9

class DashboardController < ApplicationController
  def index
    @users = UserList.new(current_user,
                          page: params[:page],
                          per_page: params[:per_page],
                          sort_by: params[:sort_by],
                          order_asc: params[:order_asc]).all
  end
end

Note that we don’t even need to specify the namespace.

Example with Models

Pretty much the same thing with models.

1
2
3
4
5

class User < ActiveRecord::Base
  def can_follow?(user)
    FollowingPolicy.new(self, user).can_follow?
  end
end

with files structure

1
2
3
4

models
├── user
│   └── following_policy.rb
└── user.rb

and possible content

1
2
3
4
5
6
7
8
9
10
11
12
13
14

# app/models/user/following_policy.rb
class User
  class FollowingPolicy
    attr_reader :current_user, :other_user, :account_verification

    def initialize(current_user, other_user)
      @current_user = current_user
      @other_user = other_user
      @account_verification = current_user.account_verification
    end

    # ...
  end
end

As a result – your code is more logically organized. It would be pretty easy to guess the locations of classes while exploring code – your app will still look like a Rails app.

And you’ll never afraid to extract one more single responsibility class, knowing that it is going to be small and “local” and won’t conflict with other’s classes.

What goes to lib/ then? API wrappers for one example. The application-independent code, or code which doesn’t belong to any model or controller.

J.B. Rainsberger – Integrated Tests Are A Scam

• They don’t put pressure to the design
• You can’t possibly test all cases
• Introduce “Collaboration” tests
• Introduce “Contract” tests

Chris Parsons – Your Tests Are Lying To You

• Some tests are saying they’re Unit, but they’re actually Integration
• Good design is easy to test – Corey Haines
• Mockist vs Classist
• Mocks are isolated, fast & tell you about design flaws

Sandi Metz – The Design of Tests

• Messages to self – rarely tested
• Incoming messages – assert on result
• Outgoing messages – test for calling
• Outgoing queries – don’t test!
• Outgoing commands – expectations on mocks

Mocks:

Martin Fowler – Mocks Aren’t Stubs

• Mockist & behavior design VS Classist & STATE

Corey Haines – Yay! Mocks!

• Mocks lead to better design that easy to change
• OO design is about interactions & roles
• Delegate the “How”
• Don’t let mocks depend on other mocks

Gregory Moeck – Why You Don’t Get Mock Objects

• Mocks assert on messages
• Stub returns value
• Mock Roles, not concrete objects.

Gary Bernhardt – Test Isolation Is About Avoiding Mocks

• Nested stubs are telling something about the design
• Good TDDers don’t write nested mocks
• We write huge functions because there’s no pressure of testing them isolated.
• Isolated tests are microscope of object interactions
• Don’t let your tests make code less readable
• Don’t isolate “Collaborator” classes

Piotr Solnica – Mocking and Ruby

• Mock only what you own If you don’t own it, you don’t have control on it’s evolution
• Don’t mock just for speed
• Be aware that mocks introduce maintenance costs
• Keep mocks simple
• Mock rarely

Is TDD Dead?

series: Part 1 – 5

GRASP(1) stands for General Responsibility Assignment Software Patterns and Principles.

Why it’s important?

Responsibilities Assignment is one of the most important skills in OOP.

The two major problems of relatively large codebases – code is messy and code is coupled. Usually it’s messy because it’s coupled. And often times the cause is wrong responsibilities assignment.

So, GRASP helps to effectively distribute responsibilities between objects.

These patterns and principles are:

• Controller
• Creator
• High Cohension
• Indirection
• Information Expert
• Low Coupling
• Polymorphism
• Protected Variations
• Pure Fabricaton

Controller

Controller is an object within the system which handles incoming parameters and delegate work to others.

That’s what “C” in “MVC” for. In Rails we have our Controllers, which handle incoming requests. But, according to GRASP, they should meet a few requirements:

• The controller should delegate the work that needs to be done to other objects
• It only coordinates or controls the activity
• It should not do much work itself

So, in other words, the controller should be skinny. Maybe so skinny it can only process incoming parameters and render results. All other work should be delegated if possible.

Creator

Creator is an object, which creates other objects.

If the one class instance have enough data to create other class instance (or form other class instance) – it should proceed with creation.

That’s how you extract responsibilities. By gathering together a related data chunks with methods, required for its processing in a separate class, which instance can be used in current context.

$RAILS_ROOT/lib is your friend at this time. But if this folder grows tremendously, it’s a clear sign you need a Service Layer(2).

High Cohension

The responsibilities of a given element should be strongly related and highly focused.

But Rails models usually look like a bunch of unrelated methods, just happening to use the data from one database table. So, “Fat Models” strongly violate this principle. Good news there’s plenty of ways(3,4) to decompose them.

Speaking of modules and “Concerns”, it is kind of cheating(5), because you’re not taking responsibility away, you’re hiding it. But it still useful in some cases, and might be a first step on gathering and extracting related pieces of functionality.

Indirection

The Indirection pattern supports low coupling (and reuse potential) between two elements by assigning the responsibility of mediation between them to an intermediate object.

MVC shows a good example of Indirection. Views don’t know anything about the Models(or shouldn’t anyway), because there’s a Controller between them.

But in a complex system that’s not enough. Ar Controller should not know about the Models either, talking to them through Contexts, or UseCases, or Interactors. And Controller action clearly shouldn’t be using several models at once.

Information Expert

Responsibility should be placed in a class with the most information required to fulfill it’s data.

While this is a good general approach, it better not to be in conflict with High Cohension and not to produce God-classes(aka Fat Models).

Low Coupling

Principles of Low Coupling:

• Lower dependencies between classes
• Changes in one class should not impact other classes
• Higher Reuse Potential

In Rails coupling often comes with chain(>2) of before_filters, ActiveRecord callbacks and stuff like accept_nested_attributes_for.

To reduce a number of these harmful entities, you can use Creator class and it’s variations. Need to synchronize a creation of two or more models during single HTTP request? Use an Interactor or UseCase in your controller and make the process as clear as possible. Ideally, your models should not know about each other more than they are related via has_many/belongs_to associations.

Polymorphism & Protected Variations

According to Polymorphism, responsibility of defining the variation of behaviors based on type is assigned to the types for which this variation happens.

The Protected Variations pattern protects elements from the variations on other elements (objects, systems, subsystems) by wrapping the focus of instability with an interface and using polymorphism to create various implementations of this interface.

Sandi Metz excellent quote(6):

No object in your system should have to know the class of any other object in order to know how to behave. Everything is a Duck. Tell the Duck WHAT and the Duck should know HOW.

Pure Fabrication

A Pure Fabrication is a class that does not represent a concept in the problem domain, specially made up to achieve low coupling, high cohesion, and the reuse potential thereof derived (when a solution presented by the Information Expert pattern does not). This kind of class is called “Service” in Domain-driven design.

References:

• Wikipedia – General Responsibility Assignment Software Patterns
• Rails and Pipes(DDD notes)
• Code Climate Blog – 7 Patterns to Refactor Fat ActiveRecord Models
• DHH – Put chubby models on a diet with concerns
• Ryan Bates – My issues with Modules
• Sandi Metz – Ruby Case Statements and ‘kind_of?’

The summary is pretty much in this(4) Hacker News comment:

…GitHub is missing this kind of environment(IRC, Mailing List), so it’s almost inevitable that first contact between maintainers and potential contributors usually comes in the form of a pull request.

… and there’s no code review and discussion is done BEFORE a pull request, which is the main reason so many PRs are not accepted.

While it’s definitely true, it don’t have to be this way.

There’s a common mental model the Pull Request is something finished. The ready-to-ship kind of thing.

Well, not always.

In our team, we send Pull Requests as soon as there’s one commit in a new branch. Or even empty commit.

git commit -m "initial commit: User can verify their account" --allow-empty

Contributor starts with some basic ideas, small patches, failing tests. And then the PR grows collaboratively. Somebody contributes with comment. Somebody does commit. Sometimes commits are reverted and replaced with better solutions. It’s like an asynchronous pair programming with unlimited collaborators. The value is tremendous.

And PR got merged only when no one have better ideas. Ideally all team members, who are interested in keeping codebase clean and to have a collective code ownership(everyone, right?), should look through PR and leave :thumbsup: in comments. One thumb is required, others are optional(if you’re in a hurry with shipment, which you souldn’t).

Although this kind of Work-In-Progress PRs are possible only in repositories in which everyone has commit access to, I’d suggest to try this approach when sending PR from a fork. The early-on feedback is still very much valuable.

References:

• @antirez – Pull requests are not conversations
• ↑ & discussion on Hacker News
• @torvalds – “I don’t do github pull requests…”
• @madsheep – Ups and Downs of Pull Request Flow
• NEOVim pull-requests

Ruby Midwest 2011 – Keynote: Architecture the Lost Years by Robert Martin

Here’s the short summary:

“The MVC is not your applcation architecture. It’s just a tiny part of it. The real Application should have it’s own architecture(built in with the best OOP practices and patterns), and interact with your I/O(controllers) and data storage(models) via limited API.

The real Application should be in Interactors & Entities(or similar structure). It should be in the Service Layer.

Controller => Interactor => Entity => Model

Controller shouldn’t speak to the Model directly. And Model shouldn’t speak to other Models. And all the dependencies should go only one way, but not the other.”

Well, this totally ruins the Rails Way, and not really applicable directly. But that’s a good start and occasion to think about architecture, code organizing etc. Here’s some materials on the topic I found useful and pleasant to read:

• Practicing Ruby Issue #4.11 – “Responsibility-centric vs. data-centric design”
• Grouper – “Rails. The Missing Parts. Interactors.”
• ↑ & epic discussion on Hacker News
• InfoQ – Domain Driven Design Quickly
• Jared Carrol – Does My Rails App Need a Service Layer?
• Wikipedia – Data, Context and Interaction(DCI)
• Focused Controller gem
• Decent Exposure gem
• Ruby Rogues Parley discussion

1. Take a huge method and extract it to it’s own class.
2. Pass all dependencies as parameters
3. Replace body of original method with Method Object call.

Before:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28

def matches_conditions_hash?(subject, conditions = @conditions)
  if conditions.empty?
    true
  else
    if model_adapter(subject).override_conditions_hash_matching? subject, conditions
      model_adapter(subject).matches_conditions_hash? subject, conditions
    else
      conditions.all? do |name, value|
        if model_adapter(subject).override_condition_matching? subject, name, value
          model_adapter(subject).matches_condition? subject, name, value
        else
          attribute = subject.send(name)
          if value.kind_of?(Hash)
            if attribute.kind_of?(Array) || (defined?(ActiveRecord) && attribute.kind_of?(ActiveRecord::Relation))
              attribute.any? { |element| matches_conditions_hash? element, value }
            else
              !attribute.nil? && matches_conditions_hash?(attribute, value)
            end
          elsif !value.is_a?(String) && value.kind_of?(Enumerable)
            value.include? attribute
          else
            attribute == value
          end
        end
      end
    end
  end
end

After:

1
2
3

def matches_conditions_hash?(subject, conditions = @conditions)
  IsMatchesConditionsHash.(model_adapter, subject, conditions)
end

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48

class IsMatchesConditionsHash < Struct.new(:model_adapter, :subject, :conditions)

  def self.call(*args)
    new(*args).call
  end

  def initialize(model_adapter, subject, conditions)
    self.model_adapter  = model_adapter
    self.subject    = subject
    self.conditions = conditions
  end

# ======== actual logic
  def call
    return true if conditions.empty?

    if model_adapter.override_conditions_hash_matching?(subject, conditions)
      return model_adapter.matches_conditions_hash?(subject, conditions)
    end

    conditions.all? do |name, value|
      if model_adapter.override_condition_matching?(subject, name, value)
        return model_adapter.matches_condition?(subject, name, value)
      end

      condition_match?(subject.send(name), value)
    end
  end
# ========

  private

  def condition_match?(attribute, value)
    case value
    when Hash       then match_hash_value(attribute, value)
    when Enumerable then (!value.is_a?(String) && value.include?(attribute))
    else attribute == value
    end
  end

  def match_hash_value(attribute, value)
    if attribute.kind_of?(Array) || (defined?(ActiveRecord) && attribute.kind_of?(ActiveRecord::Relation))
      attribute.any? { |element| self.class.(model_adapter, element, value) }
    else
      !attribute.nil? && self.class.(model_adapter, attribute, value)
    end
  end
end

We can go deeper of course. Shave the yak completely. But that’s a good start.

Actually, in this case, the implementation was moved back to the original class with a few private methods extracted. But nice thing about Method Object – it helps to understand all the dependencies this beast have, so you can deal with it.

References:

• SourceMaking – Replace Method with Method Object

Interruptions

Interruptions are horrible. They are your productivity’s worst enemy. Jason Fried gave excellent talk(1) on that. In fact, the most important measurement of quality of your working environment (and working style) is how much uninterrupted time you can have per day.

There are external interruptions. A dozen of devices ring one after another. Notifications pop up on the screen. People come talk to us. It’s hard to get away even for 10 minutes.

And there’s also interruptions of our own. We become “tired” and “feel like we deserve a break”. We open up twitter and who knows if we come back for next 30 minutes. Or some idea just hits us in the middle of the working day, and we can’t help but think it over and over again, while, at the same time, trying to stay focused on current task.

The thing is, we can’t just shut off all notifications and don’t talk to anybody. At least not for a long time. We are team workers, and have to interact. And we can’t work without breaks all day long, but we want to control them, so a little trip to Facebook don’t become a time-wasting disaster. We don’t want our brilliant ideas to get lost, but we want to work on them on priority.

Pomodoro is here to help

So there’s a Pomodoro Technique(2). In short, it offers you to work for a fixed amount of time, and then have a fixed short break.

You set a timer to 25 minutes(canonical), and, during that time, you shut off all your notifications. Nothing and no one can interrupt you, even your lazy-self. You’re don’t let yourself to think of any extraneous thoughts. If something pops up to your mind, you write it down somewhere (if it’s worth it) to come back to it later.

After timer rings, you immediately stop what you’re doing, checking your email and other messages, you go get that co-worker who had a question. And, more importantly, you’re having a scheduled break for 5 minutes or so. It’s a good time to stand up, walk outside, get some water and fresh air, limber up(3), give your brain, eyes and whole body some rest.

This is just the right balance between work and rest. It gives ability to be interrupted and communicate only when you’re available and when you don’t mind. It also makes you more self-disciplined in general, as well as it’s a good will-power exercise.

But how ‘bout my Flow?

Yes, Flow(4). The thing with Flow is hard to get in and so easy to get out. Some of Pomodoro newbies complain that this forced break is a Flow-killer. But I don’t think it is. Well, Pomodoro helps you to get into the Flow at the first place. And, again, you don’t want to get lost for several hours for the team, draining all of your brain & body power, leaving yourself completely exhausted. Pomodoro helps to stay productive all day (days/weeks/months), not just a few Flow hours.

Yes, it is hard to go for a break when you’re in a middle of something. But it teaches you to respect your time and “protect Pomodoro at all cost”, so you can do more. Also, when it’s couple of minutes left on the timer, you should start writing down what you’re doing now, and what you’re going to do next (which is a good thing to do anyway). So, for me, that’s never been a problem to get back to the same point after a break.

But every workflow is different, and every mind is different. For example in ability to stay focused on a task for a long period of time. So, I can suggest to just try it out for a few days and see if it works for you.

Start it slow

A quick tip for Pomodoro beginners – start it slow. Maybe you would want to start with 10 minutes of high quality Pomodoro. Or even 5 minutes. And increase length over time. Because successful short Pomodoros are better than few #procastodoros.

There’s an app for that

In fact, that can be enough to use a kitchen timer (the one they’re offering(5) on the site) with just pen & paper. I know a bunch of developers who use pen & notebooks as a primary GTD tool and it works for them. And if it works for you – that’s fine. But there sure some apps. I’ll describe my favorites. Each one works best in certain circumstances.

Tomato.es (Web)

The best way to try Pomodoro out. You don’t have to install anything. Just open new tab with this application, sign in with Github or Twitter (optionally), hit Space bar and see the timer going. It’ll ring when Pomodoro is over and send Chrome’s desktop notification. And there’s a nice daily, weekly, monthly stats and even Leaderboards. After all, it’s opensource, so you can suggest (or better develop) some new features.

Teamodoro.com (Web)

This one is for team synchronization. You can’t stop and start Pomodoros, they’re just starting automatically and counter is the same for everybody. And nice and simple fullscreen view to put on external monitor/device.

Wind-up Timer (iOS)

Swipe to set a timer to desired time. It ticks in the background. It rings in the end. Nice design. It is always in your pocket or desk. Well, mostly. I was happy with it at first. But there’s no way to disable iOS notifications and keep the screen unlocked. So you basically set a timer and enable airplane mode or lock the screen. Still useful sometimes.

Pomodoro.app (OSX)

The most advanced OSX Pomodoro I’ve seen. You can configure everything. Pomodoro length, break length, automatic restarts, sounds, Growl notifications, Twitter integration, Calendar intergration and, finally, execute applescripts on Pomodoro start/end/reset/interrupt/resume. And this opens endless possibilities, like disabling all possible notifications on your Mac & Devices when Pomodoro starts, and automatically re-enable them when Pomodoro ends. And, for instance, send message to Campfire. Check out my set of pomodoro-scripts.

The app is opensource, you can compile it with XCode. Or download precompiled version here.

BreakTime (OSX)

This is not exactly a Pomodoro. It’s just locks your screen after specified amount of time, so you are forced to take a break. Sometimes I use it standalone, or accompanied with other tools. Can execute applescripts.

Thyme (console)

And, finally, the terminal solution. Which have nice progressbar, Tmux integration, and can also execute applescripts (via osascript) or any other terminal commands.

That’s it. Be productive, respect your time, and happy Pomodoring!

References:

• Jason Fried – Why work doesn’t happen at work
• The Pomodoro Technique by Francesco Cirillo
• Bathroom Break Yoga – infographic
• Flow – Wikipedia
• The Pomodoro Technique official timer
• Tomato.es
• Teamodoro.com
• Wind-up Timer
• Pomodoro.app
• Pomodoro Scripts
• BreakTime
• Thyme