But just knowing that tests prevent regressions doesn’t help much when it’s time to decide what type of test to write, or how to tell if a test is actually a good one.
Today let’s take a closer look at this topic. We’ll go over what TDD is, the principles behind a clean test (FIRST), the different types of automated tests (unit, integration, and end-to-end), and how all of that connects to the design of the code itself, not just to the guarantee that it works.
Oh, and it’s worth repeating: even though I’ll use examples with Ruby, Rails, RSpec, and Capybara, the ideas apply to any language or framework.
TDD (Test-Driven Development) is a software construction technique.
It’s pretty common for people to think TDD is just a way of writing tests before the code, but it’s a lot more than that. TDD directly influences design, because the end result needs to be testable from the start.
Robert C. Martin, in Clean Code, sums up TDD in three laws:
It’s worth clarifying here that the “production code” he keeps mentioning is the application code itself, the code that’s actually going to run and solve the problem. Think of it as the opposite of test code, which only exists to check whether the first one is behaving the way it should.
Anyway, following these laws to the letter, development happens in very small cycles, known as Red, Green, Refactor:
The cycle repeats for the next behavior, and so on.
See why summing up TDD as just “writing the test first” oversimplifies things?
What TDD actually proposes is letting the need to test guide small design decisions, one behavior at a time.
Writing the test before the code doesn’t guarantee that test is any good.
That’s where the FIRST principles come in, also presented by Robert Martin.
FIRST is an acronym:
Fast: tests need to run quickly, because they’re going to be run constantly during development. And that’s not just about comfort, think about it, if the suite takes too long, people on the team end up running tests less often, or simply avoid writing new ones, which defeats the whole point of having automated tests in the first place.
Now, what counts as fast obviously changes depending on the level of the test. Unit tests tend to be a lot faster than integration tests, which in turn tend to be faster than end-to-end ones.
Independent: a test shouldn’t depend on another one running, or on state left behind by a previous test.
A classic example of this is a test that only passes because a record was created by the previous test, without creating its own. In other words, if you run that test on its own, or change the order of the suite, it breaks, even with no real change in behavior. That’s a sign the tests are coupled in a way they shouldn’t be, each test needs to set up its own scenario from scratch.
Repeatable: the result needs to be the same no matter how many times the test runs, whether on your machine, in CI, or a month from now.
A common example is a test that checks whether a promotion is active by comparing it to Time.now, something like promotion.active?(Time.now). If the promotion’s expiration date used in the test is fixed, that test passes today and starts failing on its own once that date passes, even if nobody changed anything in the code.
On top of that, depending on an internet connection or a real external service also compromises repeatability, because the test starts failing due to network instability, not an actual problem in the application.
Self-validating: the test itself needs to decide, on its own, whether it passed or failed, through a clear expectation, like expect(result).to eq(expected). You shouldn’t need to read a log or manually check some output in the terminal.
Timely: the test needs to be written at the right moment in development, not weeks after the code already exists. In TDD, that moment is before the production code.
Now that we understand what tests need to look like, let’s understand the types of tests we can have.
There are three main types of automated tests: unit, integration, and end-to-end. Each one represents a different level of confidence and isolation.
The difference between them lies in what the test actually exercises.
What defines a test’s type is:
A question that helps a lot here is: what behavior am I testing, and which real parts does this test depend on?
A unit test checks a small, specific part of the system, which can be a function, a method, a class, or a small object responsible for a rule.
A card number validator written as a simple Ruby class is a good example:
class CardNumberValidator
def self.valid?(card_number)
# Luhn's algorithm
end
end
And its test:
RSpec.describe CardNumberValidator do
describe ".valid?" do
it "returns true for a valid card number" do
expect(described_class.valid?("4111111111111111")).to be(true)
end
it "returns false for an invalid card number" do
expect(described_class.valid?("1111111111111111")).to be(false)
end
end
end
described_class represents the class named in the outermost describe, in this case CardNumberValidator.
See how simple this test is: it doesn’t need to spin up a server, make an HTTP request, or save anything to the database. That’s why it tends to be fast, and when it fails, it’s easy to pinpoint the behavior that broke.
Also, a unit isn’t necessarily “a class”. Think of it more as a behavior boundary chosen for the test, which often maps to a class, but doesn’t have to.
There are also two common ways to think about a unit test: isolated (or solitary) and sociable.
The difference is in how each one deals with the collaborators of the object under test, that is, the other objects it uses internally to do its own work.
An isolated test replaces those collaborators with test doubles. We all know that in movies, a stunt double steps in for the actor in a scene, but still delivers what the scene needs.
In programming it’s the same idea: a double stands in for a real collaborator, controlled by the test, instead of running the actual logic behind it.
There are a few types of doubles, depending on what they do. The two most common are the stub, which just returns a predefined response when called, and the mock, where the test checks whether that collaborator was called the way it was expected to. We’ll see examples of both throughout the post.
So, if CardNumberValidator depended on another object to, say, strip spaces from the number before validating it:
class CardNumberValidator
def initialize(formatter: CardNumberFormatter.new)
@formatter = formatter
end
def valid?(card_number)
luhn_valid?(@formatter.strip(card_number))
end
end
an isolated test would swap CardNumberFormatter for a stub, making sure only the validation logic is being exercised:
formatter = instance_double(CardNumberFormatter)
allow(formatter).to receive(:strip).with("4111 1111 1111 1111").and_return("4111111111111111")
validator = CardNumberValidator.new(formatter: formatter)
expect(validator.valid?("4111 1111 1111 1111")).to be(true)
Notice the test doesn’t know (and doesn’t need to know) how CardNumberFormatter actually strips the spaces, it just defines what it expects to get back and checks whether the validator reacts to it correctly.
A sociable test, on the other hand, lets those real collaborators come into play. A validation declared with validates on a Rails model is a good example: the test calls valid? for real, letting the Active Record validation machinery run underneath, without swapping anything for a double. Even without touching the database, it’s still treated as a unit test, just a sociable one.
In large applications, this is how most unit tests show up day to day, through validators, calculators, policies, and other small domain objects, each one concentrating a specific rule without depending on much else around it.
Rails, though, has so much built in by convention that it can sometimes be hard to tell where the unit ends and the integration begins.
For example, a validation declared on the model runs inside valid? or save, along with the whole Active Record machinery behind it. That’s still a unit test, but the boundary is a lot less obvious than when the rule lives isolated in a simple Ruby class, like the CardNumberValidator we just saw.
In the end, the classification depends on what’s actually executed, not on where the file lives, or on the metadata RSpec Rails uses to identify the test, like type: :model.
An integration test checks whether different parts of the application, usually spread across different layers, like route, controller, model, and database, can correctly collaborate.
That already marks a big difference from a unit test. A unit test asks whether an isolated rule is correct. An integration test, on the other hand, asks whether several real pieces, together, produce the expected behavior, which usually involves more layers, and more points of failure, at the same time.
In Rails, request specs are the most common example:
RSpec.describe "POST /orders/checkout", type: :request do
it "creates an order" do
input = {
name: "John Doe",
email: "john.doe@gmail.com",
card_number: "4111111111111111"
}
post "/orders/checkout", params: input, as: :json
output = response.parsed_body
expect(response).to have_http_status(:created)
expect(output["order_id"]).not_to be_nil
end
end
Notice this test goes through the route, controller, parameters, Order, validations, Active Record, the database, and the JSON response. It’s not just asking whether the card number is valid, the question is bigger: do the parts needed to complete an order work together?
There’s a technical detail worth mentioning here.
Even when running post "/orders/checkout", RSpec Rails normally sends that request to the application through Rack, inside the test process itself. It doesn’t need to spin up a server on a port, or make a real network call. That’s why request specs tend to be classified as integration tests for the application, not as end-to-end.
In a more minimalist framework, like Sinatra, the equivalent usually uses Rack::Test directly:
RSpec.describe "POST /orders/checkout" do
include Rack::Test::Methods
def app
App
end
it "creates an order" do
post "/orders/checkout",
JSON.generate(input),
{ "CONTENT_TYPE" => "application/json" }
expect(last_response.status).to eq(201)
end
end
An end-to-end test goes through the system starting from an externally used interface, simulating a complete user flow. In a Rails web application, this is usually done with a system spec and Capybara:
RSpec.describe "Order checkout", type: :system do
it "allows a customer to complete an order" do
visit "/checkout"
fill_in "Name", with: "John Doe"
fill_in "Email", with: "john.doe@gmail.com"
fill_in "Card number", with: "4111111111111111"
click_button "Complete order"
expect(page).to have_content("Order confirmed")
end
end
This flow goes through the browser, page, form, JavaScript, server, controller, model, database, and the response shown back on the interface.
Capybara isn’t the browser itself, it offers a language for interacting with web applications, and uses a driver underneath, for example:
A system spec with a real browser gets closer to a complete end-to-end test. A Capybara test with Rack::Test, on the other hand, simulates navigation, but doesn’t use a real browser.
In APIs, that boundary is less agreed upon. Some people call a full endpoint test end-to-end, because it goes from the request all the way to the database. In common Rails vocabulary, though, an in-process request spec is usually treated as integration anyway. A stricter end-to-end test would boot the whole application and make a real HTTP request against an actual server.
End-to-end tests tend to be expensive to maintain and more prone to breaking for reasons that have nothing to do with the behavior being tested, like a layout change on the screen. That’s why there tend to be a lot fewer of these than the other two types.
Because of that cost, and the instability that comes with it, in practice we don’t apply the three types of tests with the same intensity. And there’s no fixed ratio between them, it varies from application to application, depending on the risk of each part of the system and how critical each user journey is.
A simple idea helps decide that: each level covers a different set of cases, without repeating what the other one already guarantees.
Let’s go back to the card number validation:
The validator’s unit test covers the algorithm’s scenarios in detail: numbers that pass Luhn validation, invalid check digit, all matching digits, nil, values that are too short, values that are too long, with spaces or dashes.
The checkout’s integration test just needs to confirm that rule is wired up to the endpoint, in other words, a POST with an invalid card number returns 422 and the right error message.
We don’t need to repeat every invalid number already covered by the unit test, right?
The end-to-end test, if there’s an interface, covers the main flow: the customer fills out the form and the order goes through. Running every algorithm case through the browser would make the suite slow and redundant without adding any extra confidence.
This distribution is usually described as a pyramid: lots of unit tests for rules with several combinations, request specs covering the important contracts of the endpoints, and few system specs for the most critical user journeys.
An example of how this usually gets organized in a Rails application, without being a fixed formula:
| Level | Examples |
|---|---|
| Unit | validators, calculators, policies, domain objects |
| Model | validations, model methods and rules |
| Integration | request specs, persistence, jobs with database access |
| End-to-end | system specs with Capybara for critical flows |
And it’s worth remembering we don’t need to test absolutely everything. Most applications don’t even come close to 100% coverage, and that’s fine. What actually deserves attention are the critical parts, the ones that, if they break, affect users drastically.
Remember I mentioned TDD influences design? That happens because writing the test first forces you to think about how that code is going to be called before thinking about how it’s going to be implemented. That relationship works both ways: code that’s hard to test is usually pointing at a design problem, not just a lack of tests.
A dependency is anything a piece of code needs in order to do its own job, whether that’s another object, an external service, or the database. It’s explicit when it shows up visibly in the code itself, usually as a parameter or argument, and it’s implicit when the code simply assumes that thing is going to be available, without declaring it anywhere.
The more implicit a dependency is, the harder it gets to test that piece of code in isolation, because the test first needs to figure out what needs to exist behind the scenes for that behavior to work.
More minimalist frameworks, like Sinatra, keep these dependencies clearly visible right in the route:
post "/orders/checkout" do
input = JSON.parse(request.body.read)
halt 422 unless NameValidator.valid?(input["name"])
halt 422 unless CardNumberValidator.valid?(input["card_number"])
Order.create!(input)
end
Each dependency shows up explicitly, right there by name: the request, the name validator, the card validator, Order, the database.
In Rails, the same rule can just be declared on the model:
validates :card_number, card_number: true
and get executed implicitly by order.save, which can trigger validations, custom validators, callbacks, and persistence in a single call. That cuts down on repetition, but it also hides part of the flow behind convention.
Testing that behavior requires knowing what Rails is doing underneath, not just what’s written right there in front of you.
Neither approach is wrong, but they call for different kinds of tests to reach the same level of confidence: in Sinatra, testing each validator in isolation already makes it clear what’s happening; in Rails, besides the isolated validator, it’s worth adding an integration test confirming the convention is actually wiring the pieces together.
Imagine a use case that sends a confirmation email after an order is placed:
class CreateOrder
def initialize(email_sender:)
@email_sender = email_sender
end
def call(input)
order = Order.create!(input)
@email_sender.send_order_confirmation(order)
order
end
end
CreateOrder receives email_sender from the outside, instead of instantiating a concrete service internally. That’s what we call dependency injection, and it’s what makes this test possible without sending a real email:
email_sender = instance_double(EmailSender)
allow(email_sender).to receive(:send_order_confirmation)
service = CreateOrder.new(email_sender: email_sender)
order = service.call(input)
expect(email_sender)
.to have_received(:send_order_confirmation)
.with(order)
email_sender here is the same kind of double we saw earlier, just working as a mock this time instead of a stub, since the check isn’t about a return value, it’s about the send_order_confirmation call actually happening.
This mock works well because CreateOrder only depends on one thing outside its main behavior, sending the email. If testing CreateOrder required mocking several unrelated dependencies just to reach a single expectation, that would be a sign the class has too much responsibility, or that its dependency management needs some adjustment.
Keep in mind that a test that’s hard to write is almost always pointing at a design problem, not a lack of testing tools. That’s the thread connecting everything we’ve seen so far.
TDD guides the construction process, FIRST guides the quality of each individual test, and testability works as feedback on the design itself: a dependency that’s hard to isolate, spread-out responsibility, or excessive coupling all show up first in how hard a test is to write, long before they turn into a problem in production.
Within that process, unit, integration, and end-to-end tests represent different levels of confidence and isolation, each one answering a different question about the system.
In Rails, these boundaries look less clear, because the framework connects route, controller, model, validation, and persistence by convention. That’s why it’s always worth remembering: the folder name shows where a test is organized, but the behavior and dependencies it exercises are what actually show its real level.
I hope this helped make the topic a little clearer.
See you next time!
]]>That’s what we call a dependency.
A common reaction, especially when you’re starting to study software design, is to think dependency is synonymous with problem, and that the goal is to eliminate as many of them as possible.
But it’s not quite like that. Sandi Metz, in Practical Object-Oriented Design in Ruby, treats managing dependencies as one of the core skills of object-oriented design, not as something to avoid at all costs, especially since in a lot of cases the dependency can be unavoidable.
So today let’s understand what a dependency actually is, why it isn’t always a problem, and how to think about it both in an isolated class and in a whole application, with multiple domains, services, and integrations.
Imagine an Enrollment class, from an online course platform, that needs to know how much of the course the student has already completed:
class Enrollment
def progress
CourseModule.new(course, student).completion_percentage
end
end
At first glance, it looks like there’s just one dependency: Enrollment depends on CourseModule. But looking more closely, Enrollment knows a lot more than that:
CourseModule;course and student, in that order;completion_percentage.This already shows an important idea: a dependency can be understood as the knowledge one part of a system needs to have about another. The more details a class knows about another, the higher the coupling between them tends to be.
And that knowledge doesn’t just come from creating the object. Even if Enrollment received the module already built, as a parameter, it would still depend on something pretty specific:
course_module.completion_percentage
In other words, it would still depend on that object responding to the method completion_percentage, even without knowing how that calculation happens internally.
This is what we call interface dependency, which is when you don’t depend on how the other component solves its own problem, you only depend on the behavior it exposes outward.
So, we can sum it up like this: a dependency exists when a component needs something provided by another component in order to do its own job.
Dependency examples usually show up at the class and object level, but the same reasoning applies at a much bigger scale, between whole domains and modules of an application (which is something we see a lot more in day to day work as devs).
Imagine that same course platform is organized into modules, and that the Certificates module needs to issue a certificate to the student as soon as they finish a course:
module Certificates
class IssueCertificate
def call(student_id, course_id)
student = Students::Student.active.find(student_id)
# ...
end
end
end
IssueCertificate is a class that does exactly what its name says: issues a certificate. It’s a common Rails pattern, a class with a single public method, usually called call, dedicated to executing a specific action.
Notice that IssueCertificate doesn’t just know a student exists, it knows the Students::Student model, the active scope, the find method, and possibly the database structure behind all of it.
On top of that, if Students changes something internally, for example swapping active for more elaborate status logic, IssueCertificate risks breaking right along with it, even though it’s from a completely different domain.
One alternative is for IssueCertificate to talk to a public boundary of Students, like an API, instead of the internal model:
module Certificates
class IssueCertificate
def call(student_id, course_id)
student = Students::Public::Api.find_student(student_id)
end
end
end
Notice the dependency didn’t disappear, Certificates still needs information that belongs to Students. But now there’s a controlled boundary between the two domains.
This is pretty similar to the idea of contracts between layers we saw in the post about layered architecture, just applied between domains instead of between presentation, business, and data.
And here’s a caveat worth mentioning, a public API isn’t automatically an abstraction. Students::Public::Api is still a concrete module, it just protects the internal details of Students::Student.
But don’t worry, we’ll come back to that difference later.
Either way, this already makes a central idea clear: managing dependencies doesn’t mean stopping domains from talking to each other. It means controlling what each one needs to know about the other.
One thing to keep in mind from the start is that every dependency has a direction.
Certificates depending on Students is a different decision than Students depending on Certificates.
And the question that matters here is: who should know about whom?
There’s no generic answer, because it depends on responsibility, stability, and how much a change on one side should (or shouldn’t) affect the other.
Let’s think about a different situation.
It would be strange for the Students module to know details about Certificates just to be able to list which courses a student has already completed. That would flip the natural relationship between the two domains, Students would end up knowing about certification just to return information that, in practice, belongs more naturally to itself.
Flipping a dependency doesn’t automatically make the design better, it just changes who depends on whom, and sometimes puts the responsibility somewhere that doesn’t make sense.
A good rule for choosing the direction is to look at how likely each side is to change.
In general, more concrete, domain-specific classes tend to change more than stable interfaces.
And just to clarify, a concrete class is a class with a specific implementation, a defined way of solving a problem, unlike an interface, which only defines the expected behavior without committing to how it’s solved internally (this is the same idea of interface dependency we saw at the start of the post).
A good example of this is Students::Public::Api itself, which we saw above.
IssueCertificate depends on the method find_student(student_id), that’s the interface, the contract it knows about. How that method solves the problem internally is the concrete part:
module Students
module Public
module Api
def self.find_student(student_id)
Student.active.find(student_id)
end
end
end
end
Now imagine that tomorrow the Students team decides to look up the student in a cache first, and only hit the database if it’s not found:
module Students
module Public
module Api
def self.find_student(student_id)
Rails.cache.fetch("student:#{student_id}") { Student.active.find(student_id) }
end
end
end
end
The implementation changed completely, but the interface, the method name, the argument it expects, and what it returns, stays exactly the same.
IssueCertificate doesn’t even find out something changed internally. That’s why interfaces tend to be more stable than concrete implementations. What changes most often is what’s inside, not the contract exposed to the outside.
And it’s not just within our own application that this applies.
We depend on String, Array, Enumerable all the time in the same way, without worrying much about it, because their interface practically never changes. An internal class built to solve a specific business rule, like IssueCertificate, is a lot more likely to have both its interface and its implementation change tomorrow.
So, whenever possible, it’s worth making dependencies point in the direction of what’s more stable.
Not every dependency carries the same risk. Two questions help identify when a dependency starts to weigh things down: how often it changes, and how many parts depend on it.
Imagine Student#full_name is used by several different modules, Certificates, Notifications, and Reports, all calling that same method:
Certificates ─┐
Notifications ─┼──→ Student#full_name
Reports ─┘
If that interface changes, for example if it starts requiring a new argument, all three modules feel the impact at the same time.
So, the more things depend on an interface, the more stable it needs to be, because the cost of changing it grows along with the number of dependents.
The riskiest scenario is exactly the combination of both things: something that changes frequently and, at the same time, has a lot of dependents.
If Students::Student were being accessed directly (without the boundary we built above) by several different modules, any adjustment to Student’s structure would turn into a risk event for the whole application.
After recognizing a dependency and evaluating how much it weighs, the next step is deciding what to do about it. There are a few techniques that help reduce the knowledge one component needs to have about another.
Without injection, IssueCertificate builds what it needs on its own:
class IssueCertificate
def call(student, course)
PdfGeneratorWrapper.new.generate(student, course)
end
end
It knows which generator to use, how to create an instance of it, and that it responds to generate.
With dependency injection, that creation happens outside instead:
class IssueCertificate
def initialize(generator:)
@generator = generator
end
def call(student, course)
@generator.generate(student, course)
end
end
IssueCertificate
.new(generator: PdfGeneratorWrapper.new)
.call(student, course)
Dependency injection is basically that, an object receives from the outside what it needs to work, instead of building that dependency on its own.
This doesn’t eliminate the dependency, IssueCertificate still needs something that responds to generate(student, course). What changes is the type of knowledge. Before, it knew which concrete class to use and how to create it. Now, it only knows which behavior it expects to receive.
Much better, right?
This also makes testing a lot easier, because you can inject a fake generator without touching IssueCertificate at all.
Isolating a dependency means concentrating the knowledge about it in a single place. The dependency is still there, the gain is avoiding that knowledge being spread across several points of the application.
And believe me, in very large applications, isolation is essential.
Going back to the Enrollment example from the start, imagine progress also needs to apply a weight:
def progress
weight * CourseModule.new(course, student).completion_percentage
end
Creating the CourseModule is mixed together with the calculation. But we can separate it:
def progress
weight * course_module.completion_percentage
end
def course_module
@course_module ||= CourseModule.new(course, student)
end
Now progress only knows how to use the module, and course_module knows how to build the object.
The ||= here guarantees the object is only created the first time course_module is called, and reused after that, which is usually called lazy initialization, where creation is delayed until the moment it’s actually needed.
We can also isolate the method call itself, not just the creation. progress still knows course_module responds to completion_percentage:
def progress
weight * completion_percentage
end
def completion_percentage
course_module.completion_percentage
end
That specific knowledge stays concentrated inside completion_percentage. If tomorrow the progress calculation comes from somewhere else, only that method needs to change.
This same principle shows up when the application depends on an external library we don’t control. Imagine the certificate’s PDF generation uses an external gem, with an interface based on positional arguments:
ExternalPdfLib::Generator.new(student.name, course.title, Time.current)
Since we don’t control that interface, creating a wrapper (a layer that wraps this external dependency and hides its details from the rest of the application) helps concentrate that knowledge:
module PdfGeneratorWrapper
def self.generate(student:, course:)
ExternalPdfLib::Generator.new(student.name, course.title, Time.current)
end
end
The rest of the application now calls PdfGeneratorWrapper.generate(student: student, course: course), without needing to know the exact order of arguments the gem expects.
Only the wrapper knows about that peculiarity.
Isolating this kind of logic in a dedicated object, similar to a service object, is a common way to contain that knowledge in one place.
And here’s a caveat worth mentioning, it doesn’t make sense to create a wrapper for every gem or every external call in the application. The abstraction needs to solve a real problem, not exist just for the sake of existing.
In the dependency injection example, IssueCertificate calls @generator.generate(student, course).
class IssueCertificate
def initialize(generator:)
@generator = generator
end
def call(student, course)
@generator.generate(student, course)
end
end
That call represents an abstraction, because it only expresses the behavior IssueCertificate needs, without determining how it’s going to be carried out.
PdfGeneratorWrapper, which we just saw, is a concrete implementation of that behavior, but it isn’t the only possible one.
In a test, for example, we can create another implementation, a fake generator that just returns a fixed PDF, without calling the real gem:
class FakePdfGenerator
def generate(student, course)
"Fake PDF for #{student.name}"
end
end
And when writing the test, it’s this fake implementation that takes the place of the real one:
IssueCertificate
.new(generator: FakePdfGenerator.new)
.call(student, course)
Notice that PdfGeneratorWrapper and FakePdfGenerator fulfill the same contract, both respond to generate(student, course). That’s why IssueCertificate works the same way in both cases: it only knows the abstraction, the expected behavior, it doesn’t know (and doesn’t need to know) which of the two implementations it’s receiving.
In Ruby, we don’t normally declare this interface explicitly, the way we would in a statically typed language. The expectation that the object responds to generate shows up implicitly, through the methods we call on it. This is usually called duck typing, what matters is that the object responds to the expected method, not which class it belongs to.
In Clean Architecture, Robert C. Martin describes something similar through the Dependency Inversion Principle, depending on the behavior you need, not on the specific implementation that currently provides it. It’s the same idea as Sandi Metz’s, just described at a scale that already thinks in terms of whole components, not just objects.
And it’s worth reinforcing that earlier caveat, Students::Public::Api creates a boundary, but it’s still a concrete implementation, a specific module with a specific method. Boundary and abstraction are similar concepts, but they aren’t the same thing.
A common mistake is treating dependency as synonymous with problem. Every application depends on Ruby, on Rails, on gems, on other domains, on internal and external services. That’s unavoidable, and that’s fine.
The question that actually matters isn’t whether an arrow A → B exists. It’s what kind of knowledge crosses that arrow.
A simple, stable, intentional dependency can be perfectly acceptable without any special technique applied to it.
It’s also worth telling dependency and coupling apart here.
A dependency is the fact that one component needs another to work. Coupling, on the other hand, describes how tightly those parts are tied together, and how much changes in one affect the other.
They’re related concepts, but they aren’t synonyms.
Alright, now that we’ve talked through all of this, when you run into a new dependency, or review an existing one, a few questions help decide what to do with it.
The first one is: what exactly does this code depend on?
A specific implementation, a model, a public API, a behavior contract?
Not every dependency calls for the same kind of care.
Another useful question: how much does this component know about the other one?
Does it only know the behavior it needs, or does it also know internal details, like database structure, queries, and payload format?
It’s also worth considering: how often does this dependency change, and how many parts depend on it?
A combination of frequent change with a lot of dependents is a sign that point deserves extra attention.
And, before going and creating abstractions for everything, does this abstraction solve a real problem?
Not every dependency needs to turn into an interface, gateway, adapter, or wrapper. Adding a layer where it isn’t necessary just adds complexity without reducing any risk.
At the end of the day, what we can take away from today isn’t ways to eliminate dependencies. It’s understanding that they’re unavoidable, and that the amount of knowledge crossing these relationships is a design decision, not an accident.
An application that’s easier to change is, generally, an application where each component only knows what it actually needs to know about the others.
If you want to go deeper on this topic, the two books that guided this post are great starting points: Practical Object-Oriented Design in Ruby, by Sandi Metz, and Clean Architecture, by Robert C. Martin.
See you next time!
]]>It’s one of the best known principles when it comes to code design. Sandi Metz dedicates a whole chapter to it in Practical Object-Oriented Design, and Robert C. Martin talks about it a lot in both Clean Code and Clean Architecture.
Even though it’s a well known principle, it gets a lot trickier when you try to apply it outside the classic single-class example.
So let’s understand what it is, see how it shows up in a class, and then expand that thinking to a bigger application context, where it’s not just classes, there’s services, modules, jobs, lots of things happening at the same time.
According to Sandi Metz, a class should do the smallest useful thing possible. In other words, it should have a single responsibility.
The most famous phrase about this, from Robert C. Martin, is: a class should have one, and only one, reason to change.
The definition doesn’t say “do only one thing”, it says “reason to change”. That difference matters a lot, and we’ll come back to it later.
Let’s look at an example. Imagine an Order class in an e-commerce app:
class Order < ApplicationRecord
def total
items.sum { |item| item.price * item.quantity }
end
def apply_discount(coupon)
total - coupon.value
end
def send_confirmation_email
OrderMailer.confirmation(self).deliver_now
end
end
This class calculates the order total, applies a discount, and also sends an email.
So there are three different reasons for this class to change:
If any one of these three things changes, Order changes too, even if the other two stay exactly the same.
We can split it like this:
class Order < ApplicationRecord
end
class OrderPricer
def self.total(order)
order.items.sum { |item| item.price * item.quantity }
end
end
class DiscountCalculator
def self.apply(order, coupon)
OrderPricer.total(order) - coupon.value
end
end
class OrderConfirmationMailer
def self.send(order)
OrderMailer.confirmation(order).deliver_now
end
end
Now each class has only one reason to change. If the discount rule changes, only DiscountCalculator is touched. Order stays the same.
You might be thinking “wait, isn’t this creating too many classes?”
That’s a pretty common concern. Robert C. Martin himself talks about this fear, of creating too many small classes and the code ending up too spread out to follow.
And from my point of view, it’s a trade-off. Either you simplify thinking about future maintenance, or you keep everything together out of fear of “creating too much code” and pay that price down the road, when you need to change one rule without affecting the others.
So yeah, splitting things up too much can feel like overkill, especially at the start and in small projects. But in large applications, with a lot of people working on the same code, this separation tends to pay off quite a bit later on.
And deep down, it’s a choice, there’s no absolute right or wrong. Sandi Metz herself talks about this in the book:
A good designer understands this tension and minimizes costs by making informed tradeoffs between the needs of the present and the possibilities of the future.
It’s also worth quickly talking about some good practices Sandi Metz brings up in the book, that help the code keep respecting SRP as it evolves, without needing to refactor everything every time a rule changes.
One point she raises is avoiding accessing instance variables directly inside the class itself. It seems trivial at first, but using @type and @value directly across several different methods spreads the knowledge of how that data is stored throughout the whole class:
class Coupon
def initialize(value, type)
@value = value
@type = type
end
def apply(total)
@type == :percentage ? total - (total * @value / 100.0) : total - @value
end
end
Hiding these variables behind methods, any new rule about them stays concentrated in one place:
class Coupon
def initialize(value, type)
@value = value
@type = type
end
def apply(total)
percentage? ? total - (total * value / 100.0) : total - value
end
private
attr_reader :value, :type
def percentage?
type == :percentage
end
end
If the rule for “what counts as a percentage coupon” changes, only percentage? needs to change.
She also talks about a similar problem with raw data structures, like arrays and hashes. If the code depends on a position in an array or a key in a hash to work, any change to that structure breaks everything that depends on it:
def total(line_items)
line_items.sum { |item| item[:price] * item[:quantity] }
end
If someone renames the :price key to :unit_price, this method breaks, and it’s probably not the only place accessing that hash this way. Encapsulating this in an object fixes it:
LineItem = Struct.new(:price, :quantity) do
def subtotal
price * quantity
end
end
def total(line_items)
line_items.sum(&:subtotal)
end
Whoever calls total doesn’t need to know how a LineItem stores its data internally, just that it responds to subtotal.
And finally, this same reasoning also applies inside methods, not just between classes.
A method that validates, calculates, and formats at the same time has, in practice, the same reasons to change that a poorly split class would have, just on a smaller scale:
def apply(total)
raise ArgumentError, "invalid coupon" if value.negative?
percentage? ? total - (total * value / 100.0) : total - value
end
Separating validation from calculation fixes this the same way:
def apply(total)
validate!
percentage? ? total - (total * value / 100.0) : total - value
end
private
def validate!
raise ArgumentError, "invalid coupon" if value.negative?
end
So far, this is the most common example we see when SRP comes up. But what happens when we step outside the class level?
We’ve talked about SRP in a relatively isolated class. In this scenario, we just need to ask ourselves which behaviors really belong to that object.
It’s the kind of reasoning Sandi Metz proposes when “interrogating” a class. If a method seems to answer a question that shouldn’t be asked of that object, there might be a responsibility in the wrong place.
In a real application, though, there are a lot more candidates to take on a responsibility. A rule can live in an entity, a value object, a use case, a policy, a job, an adapter, or some other component of the application.
Because of that, the question stops being just “does this class do more than one thing?” and becomes “who should know about or execute this behavior?”.
Let’s go back to the same Order we used above. Questions about its state, its items, or its total value are still the order’s own problem, that doesn’t change:
order.total
order.issued?
order.line_items
But not everything that mentions “order” is Order’s responsibility.
Sending the confirmation email, charging the customer, or coordinating the whole checkout flow are different responsibilities, each with its own reason to change. They can live in a mailer, a payment gateway client, or a use case that orchestrates the whole process:
OrderConfirmationMailer.send(order)
PaymentGatewayClient.charge(order)
SubmitOrder.call(order)
SRP is still the same principle as always. What changes in a larger application is the number of possible places for that responsibility to live, and that’s what makes it harder to see.
Another one of Robert C. Martin’s definitions helps a lot here. According to him, a “reason to change” is tied to a person or group of people interested in that change, what he calls an actor.
This gets easier to see when we look at a whole component, not just loose methods. Imagine a component called OrdersService:
class OrdersService
def process(order_params)
Order.create!(order_params)
end
def monthly_report
Order
.where("created_at >= ?", 30.days.ago)
.group(:status)
.count
end
def notify_marketing(order)
MarketingNotifier.order_confirmed(order)
end
end
At first glance, the methods look related because they all mention orders. But they represent different knowledge:
process knows the operational rules for creating ordersmonthly_report knows analytics and reporting needsnotify_marketing knows the marketing communication processDoing three things isn’t really the problem. The problem is that these three parts can change independently, for different reasons.
A new rule for creating orders shouldn’t force the same component to change along with report generation. In the same way, a change in marketing communication shouldn’t put order processing at risk.
We can separate these responsibilities:
class ProcessOrder
def call(order_params)
Order.create!(order_params)
end
end
class MonthlySalesReport
def generate
Order
.where("created_at >= ?", 30.days.ago)
.group(:status)
.count
end
end
class NotifyMarketingAboutOrder
def call(order)
MarketingNotifier.order_confirmed(order)
end
end
The exact names don’t matter, and neither does the fact that we ended up with three classes. What matters is that each component now concentrates knowledge that tends to change together.
Deep down, OrdersService is still just a class. That’s how we always express any unit in Ruby, whether it’s a domain, a module, or a whole service, the syntax doesn’t change. What changes is what that component represents inside the application, and how many different actors depend on it.
This same logic shows up in units we don’t usually think of as a “class”, like a job. Imagine a job that closes out an order’s checkout:
class CheckoutJob < ApplicationJob
def perform(order)
order.update!(status: :paid)
InvoiceGenerator.call(order)
LoyaltyPointsCalculator.credit(order)
MarketingNotifier.order_confirmed(order)
end
end
The job doesn’t know the internal rules of each step, LoyaltyPointsCalculator handles points, InvoiceGenerator handles the invoice. What CheckoutJob concentrates is the orchestration: deciding which steps happen, in what order, and what to do when one of them fails.
And that’s where the problem lies, the four steps end up sharing the same fate, if any of them fails, ActiveJob retries the whole job again. A failure in MarketingNotifier, for example, makes the job reprocess the payment and generate the invoice again, even if those two steps had already succeeded on the first attempt.
If the finance team wants invoice generation to have its own retry policy, without re-running payment and loyalty along with it, the whole CheckoutJob needs to change, because the orchestration of the four steps lives in one single place.
Here, the reason to change is the coordination between teams, not the knowledge of each one’s rules. Same problem as OrdersService, just that the unit is now a job.
We can fix this by separating orchestration from execution. Instead of the job calling the four steps in sequence, sharing the same fate, each step becomes its own job, triggered independently.
class CheckoutJob < ApplicationJob
def perform(order)
order.update!(status: :paid)
GenerateInvoiceJob.perform_later(order)
CreditLoyaltyPointsJob.perform_later(order)
NotifyMarketingJob.perform_later(order)
end
end
class GenerateInvoiceJob < ApplicationJob
def perform(order)
InvoiceGenerator.call(order)
end
end
class CreditLoyaltyPointsJob < ApplicationJob
def perform(order)
LoyaltyPointsCalculator.credit(order)
end
end
class NotifyMarketingJob < ApplicationJob
def perform(order)
MarketingNotifier.order_confirmed(order)
end
end
Now CheckoutJob has just one responsibility: confirming the payment and triggering the other steps, without waiting for or depending on their result. Each queued step runs independently, if NotifyMarketingJob fails, only it gets reprocessed by ActiveJob. Payment and invoice aren’t touched again.
And each job now has just one reason to change, matching a single actor, GenerateInvoiceJob changes when the tax rule changes, and the finance team decides its own retry policy. CreditLoyaltyPointsJob changes when the loyalty rule changes. NotifyMarketingJob changes when marketing communication changes.
Before, these four reasons to change were tied together in the same perform, sharing the same retry policy without anyone having decided that on purpose.
The separation doesn’t reduce code, it decouples the fate of each responsibility from the others. It’s the same logic as Order at the start of the post, just applied at the level of asynchronous execution.
If you’ve already read the post about coupling here on the blog, this is pretty similar to that idea that a design concept isn’t tied to a single form, it repeats itself across different units of the application: class, service, job, module.
At the end of the day, SRP isn’t a rule exclusive to models or small classes. It’s a way of thinking about distributing responsibility: group together what changes together, separate what changes for different reasons, whether that’s a class, a service, or a job.
In a larger application, the principle still holds. It just gets harder to see, because now there are more units, layers, and integrations competing for space for each responsibility.
Thinking about the Single Responsibility principle day to day isn’t always easy (I say that from experience). So a question that helps a lot, at any level, whether it’s a class, service, or module, is: who’s going to ask for a change here, and why?
If the answer involves more than one team, or more than one reason that has nothing to do with the other, that’s a sign that component is carrying more than one responsibility.
Another tip, this one from Sandi Metz herself, is trying to describe what that component does in a single sentence. If you need to use “and” or “or” along the way, like “processes the order and sends a marketing notification”, that’s already a sign there’s more than one responsibility in there.
It’s also worth paying attention to who touches that file, and why. If the commit history shows changes from completely different teams, one day it’s the finance team adjusting the invoice, another day it’s marketing changing the email copy, that’s a pretty concrete sign that different actors live in there.
And notice how much effort it takes to test. If testing a component requires mocking a bunch of unrelated things, like a payment gateway, a points calculator, and a marketing client in the same test, that’s usually a reflection of mixed responsibilities. A hard to write test almost always points to a design problem.
And remember, just like with coupling, the goal isn’t to take this to the extreme. It’s not possible, and it doesn’t make sense, to split everything into tiny components just for the sake of it. The idea is to notice where different reasons to change are mixed together in the same place, and then decide whether it’s worth separating them.
This is one of those principles that seems simple when you only look at the single-class example, but that gains another layer of complexity as the application grows and more people start working on it.
I hope this post helped you think about SRP in a slightly broader way.
See you next time!
]]>There’s no exact answer to that question, but because of it, I decided to talk a bit about how my own experience with interviews has been.
Before anything else: what I’m bringing here is based on my personal experience, okay? The scope is pretty specific. I’m talking about mid-level developer roles (and senior in some cases), with a Ruby on Rails, React, and JavaScript stack, at Brazilian and, mainly, international companies.
Unfortunately, I don’t have records of my junior interviews because, back then, I didn’t document anything. So this post focuses on what I’ve been through since then.
And of course, every company organizes the process differently. The point here isn’t to say your interview is going to look exactly like this, but to show some formats I’ve come across and things that can help with preparation.
That said, let’s get into it.
Processes vary a lot. Some companies start with a recruiter, some put you straight into a conversation with the CTO. Some processes have five clearly defined stages, and some lay out a full roadmap and then change everything halfway through.
One thing that became pretty clear to me is that the name of a stage doesn’t always describe what’s going to happen. An “initial chat” can be purely informational, but it can also be the first, deeper evaluation of the process.
Because of that, before each interview, it’s worth trying to understand two things: what stage it is, and who you’re going to talk to.
Usually, the first stage of a hiring process is with someone from recruiting.
Here’s a tip: before joining the call, it’s worth searching LinkedIn for the name that shows up on the meeting invite. In some cases, this first conversation can actually be directly with someone from engineering, and knowing that ahead of time changes a lot about how it makes sense to prepare.
In general, what usually comes up in a conversation with a recruiter is:
That last one came up in almost every process I’ve been through, so it’s good to go in already knowing how you plan to answer. One thing I learned is that there’s no problem asking if the company has a salary range, in a lot of cases they’ll tell you. But when they don’t define one, you’ll have to name a number yourself.
If it’s someone from recruiting, you probably won’t need to go too deep into the technical side. What matters most tends to be explaining your experience clearly and connecting what you’ve already done with what the role is looking for.
Something that helped me a lot was rehearsing beforehand, especially for interviews in English. It gave me a lot more fluency when speaking and helped me stay focused on what I actually needed to show.
In a lot of processes, it’s normal and expected to have a conversation with someone from engineering, a CTO, or some other leader. This can happen right in the first stage or at another point in the process. It really depends on the company.
And this conversation usually ends up being a lot more technical than the stage’s name makes it sound.
I’ve had a conversation that didn’t involve any code or exercise, but where I needed to explain a project in depth: what the problem was, what decisions were made, what trade-offs existed, and what I’d do differently today.
I’ve also been asked things like:
Among many others.
So it’s worth showing up prepared to talk not just about what you did, but why you did it that way.
Something I learned is that it helps a lot to have two or three projects you really know well. You don’t need to memorize a speech, but it’s good to be able to explain the context, your part in it, the decisions, the outcome, and what you learned.
Some processes have a stage focused on culture and behavior, more about understanding how you work and seeing if it fits the way the company works.
If the company has a page about its values, it’s worth reading it before the interview. They’ll probably be looking for behaviors aligned with those values in what you say.
So if the company values things like independence and async communication, for example, it doesn’t look great if you show that you prefer daily check-ins or need a lot of validation from the team to make decisions.
And remember: at this stage, the focus is behavioral.
Once, I had an interview like this conducted by two engineers, and because they were engineers, I thought I needed to nail all the technical details.
I remember there was a question about how I deal with disagreement on a team, and I ended up talking about the system’s architecture. That wasn’t what they wanted to understand.
What mattered there was my attitude, how the situation got resolved, and what I learned. The technical part was just context.
The topics tend to circle around:
When we get nervous, the tendency is to stretch out answers and lose the thread. A structure that can help is thinking in terms of situation, action, result, and learning.
You don’t have to be rigid about it, but keeping that sequence in mind avoids answers that start in one place and end up somewhere else entirely.
And this stage can also tell you a lot about the company.
During these conversations, I’ve been able to get a better sense of how often meetings happen, how much autonomy the team has, and how decisions tend to get made. While you’re being evaluated, you’re also observing.
This was, by far, the stage with the most variation across the processes I’ve been through. It can be live coding, conceptual questions, a business rule, a take home exercise, an architecture diagram, or a mix of several of these. I’ll mostly talk about the formats I’ve actually experienced.
Live coding is the kind of interview where you need to code live, sharing your screen or using some online editor. It’s shown up for me as:
You can’t always know the format ahead of time, so it’s worth preparing both for your own environment and for using a more limited online editor.
What tends to get evaluated isn’t just whether you reach the right solution, but how you interpret the problem, how you react when something goes wrong, and how you communicate while solving it.
In one of the interviews I did, the exercise was to go through a string, record the position of each letter in a hash, and then sort the results.
I got to a working solution, but with a less elegant approach. Even so, I was able to move forward.
What stuck with me from that is that starting with something simple usually beats getting stuck waiting for the perfect solution to show up.
In another one, the exercise involved calculating how many weeks a certain amount of medication would last. The simple scenario was fine, but when the quantity didn’t divide evenly into whole weeks, things got complicated. The problem wasn’t the language, it was translating a math rule into code under pressure.
Both examples reminded me of something important: it’s always worth practicing logic. Being able to solve a problem from scratch, without AI, without Stack Overflow, is exactly what live coding is going to demand from you.
AI is great for day to day work, but in live coding you won’t have it by your side. If you’re used to relying on it to think, it can be tough when it’s not available. It’s worth training without it every once in a while, just to keep that muscle active.
A tip that makes a difference: talk out loud while you solve it.
Explain what you understood about the problem, what path you plan to follow, what you’re testing. Staying silent makes it harder to evaluate you, because the other person only sees the code and can’t follow your reasoning.
It feels weird at first, but it’s something worth practicing.
Oh, and some companies let you check documentation during the exercise. If that’s the case, great, because in day to day work nobody remembers everything off the top of their head.
Besides live coding, you might get questions about concepts and technical situations:
These questions aren’t always the “explain concept X” type. Sometimes the person lays out a situation and wants to understand how you think through building a solution.
In one interview, I was asked how I’d handle a migration on a table that was constantly receiving data and couldn’t be locked. The question wasn’t just about knowing how to add a column, it was about thinking through the old data, the new records coming in during the migration, temporary compatibility, and the risk of downtime.
Organizing your answer in stages, before, during, and after the change, helps a lot in these cases. And it’s fine to take a few seconds to organize your thoughts before you start talking.
Some companies ask for an assessment more focused on architecture, usually as a system design exercise during the interview or as an artifact sent beforehand, like a diagram of a real project, to discuss live afterward.
Unlike live coding, the focus isn’t on writing the implementation. The idea is to understand how you organize a bigger problem and what points you consider before proposing a solution.
When the company asks for an artifact beforehand, it’s worth asking: is it a pass or fail step, or just a starting point for a conversation? What scale are they expecting to see? Do they want the project you know best, or the biggest system you’ve worked on?
Things like that will help you figure out how to put the artifact together.
Something I picked up on over time is that the interview isn’t just a test for you to pass. It also tells you a lot about the company.
How the process is run, whether the criteria are clear or implicit, whether the stages are respected or change without notice, whether people show up prepared, all of that says a lot about how the company organizes itself and makes decisions day to day.
So while you’re being evaluated, it’s important to observe too. You don’t need to leave every conversation only thinking about whether the company liked you.
It’s also worth thinking about whether what you heard makes sense for the kind of place you’d like to work at. Especially since that’s the company where you’ll be spending a good chunk of your day.
Everything I brought up here is experience I still use to try to improve with every process. There’s no formula, but there is practice, self assessment, and, over time, more clarity about what worked and what didn’t work for you.
And that goes both ways: both to get better at interviewing and to understand if the place evaluating you is really the place where you want to be.
See you next time!
]]>But what exactly is it, and why does it matter? Let’s talk about it.
According to Mark Richards, layered architecture is one of the most common architectural styles, especially in enterprise applications. The idea is to organize the system into groups of well defined responsibilities, which we call layers. Each layer has a specific role, and they communicate with each other in an organized way.
The main goal is to separate responsibilities so that each part of the system takes care of just one thing, without needing to know implementation details from the others.
Notice how similar this is to the way Rails separates its folders and files?
A classic example is the split into three layers: presentation, business, and data.
In a Rails application, this shows up pretty directly:
Presentation → Controllers, Views
Business → Models, Service Objects
Data → ActiveRecord, repositories
When a user makes a request, it hits the controller (presentation), which calls the business logic, which in turn accesses the data. The flow goes down through the layers.
Alright, but having layers isn’t enough. What really makes this style work is the isolation between them.
Isolation means each layer only knows what it needs to do its own job.
The presentation layer doesn’t need to know how data is stored in the database. The data layer doesn’t need to understand the business rules.
This is guaranteed by contracts between layers. Each layer exposes a clear interface to whatever’s above it. The layer above calls that interface, without depending on the details of how it was implemented underneath.
Think about it this way: the controller calls OrderService.complete(order). It doesn’t need to know if that hits the database, sends an email, calls an external API, or anything else. It only knows that contract exists and what it’s going to get back.
This reduces coupling between the parts of the system. If you need to change how an order gets completed, you change the service. The controller doesn’t need to be touched.
Oh, and if you want to know more about coupling, I suggest checking out this post here on the blog.
Let’s look at an example. Imagine a controller that fetches a user’s recent orders:
# without isolation: the controller knows too much
class OrdersController < ApplicationController
def index
@orders = Order.where(user_id: current_user.id)
.where("created_at >= ?", 30.days.ago)
.order(created_at: :desc)
end
end
This controller is navigating straight through the database structure. If the query changes, the controller changes with it.
With isolation:
# with isolation: the controller only knows the contract
class OrdersController < ApplicationController
def index
@orders = Order.recent_for(current_user)
end
end
class Order < ApplicationRecord
scope :recent_for, ->(user) {
where(user: user)
.where("created_at >= ?", 30.days.ago)
.order(created_at: :desc)
}
end
Now the controller only knows there’s a recent_for. The details stay hidden inside the data layer.
And what happens when that contract gets ignored?
Imagine another part of the application also needs a user’s recent orders. Without isolation, someone’s going to copy the same query into the new controller. When the rule changes, for example the window going from 30 to 60 days, who remembers to update it everywhere? That’s the kind of problem that starts small and keeps growing along with the application.
With recent_for centralized in the model, the change happens in one place. Whoever calls it doesn’t even need to know something changed.
This isolation also defines how the flow happens. Each request moves through the layers in sequence, top to bottom. Presentation calls business, business calls data. Always in that order.
But then a question comes up: is that flow always mandatory? Does every request need to go through every layer?
The answer depends on how the layers are defined in the system. And that’s where the distinction between closed and open layers comes in.
In a closed layers model, a request needs to go through every layer, in order, with no skipping.
In other words, the request comes from presentation, passes through business, and reaches data. It can’t go straight from presentation to the database, skipping the middle.
Presentation
↓
Business
↓
Data
This reinforces isolation because it guarantees each layer only interacts with the layer immediately below it. No layer has direct access to things outside its neighborhood.
Advantages:
The main gain is that isolation is guaranteed by the structure, not by developer discipline. This matters especially on larger teams, with devs joining and leaving. Trusting that everyone will respect the contracts on their own is risky. With closed layers, the architecture enforces it automatically.
On top of that, a request’s flow is easy to follow. You know it’s always going to go through the same sequence, so when something breaks, you know where to look.
Disadvantages:
The problem shows up in simple cases.
Imagine a report screen that just needs to count how many orders were placed this month. There’s no business rule involved, it’s just a direct database query. But with closed layers, you still have to create a service that calls the model, that calls the database. Layers just to follow protocol, without adding anything.
In high volume systems, this can also weigh on performance. Every request passes through more points, which means more execution time.
Mark Richards calls this problem the sinkhole anti-pattern: when most requests just pass through the layers without any logic, the cost of the indirection stops being worth it.
And that brings us to the alternative for when this mandatory path starts weighing more than it helps.
In the open layers model, some layers are optional. The request can skip one of them when it makes sense.
Presentation
↓
Business ← can be skipped
↓
Data
Imagine you have an endpoint that just needs to list an order’s available statuses. There’s no business logic involved. In this case, it makes sense for the controller to access the data directly:
class OrdersController < ApplicationController
def statuses
render json: Order.statuses.keys
end
end
No service in between, no indirection. Simple, fast, direct.
Advantages:
For cases like this, where the middle layer isn’t doing anything useful, the flexibility to skip it is welcome. The code stays leaner and you avoid creating abstractions that exist just to exist.
Disadvantages:
The risk is the team starting to skip layers frequently, without much criteria. At first it seems reasonable: “this case is simple, it doesn’t need the service.” But that accumulates, and over time it gets hard to tell which exceptions were justified and which turned into shortcuts. A request’s flow stops being predictable, and understanding the whole system gets harder.
In practice, most applications use a mix of both models. Closed layers as the general rule, with specific exceptions where skipping makes sense, as long as the team is disciplined about telling one from the other.
Now that we understand what layers are and how they relate to each other, it’s worth taking a more critical look at this style: what does it solve well, and where does it start showing limitations?
Like any architectural decision, there’s no absolute right or wrong. It depends on the application’s context.
On the positive side, it’s a style that’s simple to understand and easy to explain to teams. Any dev who joins a project organized in layers can find their way around quickly: where’s the logic? In business. Where’s the query? In data. The flow follows a clear direction and each part has a defined responsibility, which makes it easier to maintain and test.
On the negative side, in simple systems it can create unnecessary indirection. Sometimes you end up creating a service layer that just passes the call through to the model, without doing anything special. Extra code with no real gain.
There’s also the risk of overdoing the abstractions. It can become a habit to create service objects, repositories, and interfaces for everything, even when it’s not needed. Abstractions have a cost. More files, more jumps to understand the code, more things to maintain.
And when the application grows a lot, two problems show up together:
That said, these problems tend to show up once the application has already grown quite a bit. For most day to day cases, layered architecture handles what needs to be handled just fine.
I hope this made it clearer how this style works!
See you next time.
]]>That kind of thinking isn’t wrong, but it only captures part of an idea that goes further than that.
To get started, let’s understand what coupling actually is.
Coupling, according to Mark Richards, is when components are connected in such a way that changing one will impact the behavior of another component.
So, basically, we’re talking about the dependency between components of a system.
The more coupled the components, the harder it becomes to maintain or test them, because you’ll always depend on another component to do it.
And just to be clear, when we say “component”, it can mean a class, a module, a whole service, a domain, and so on.
Let’s think about an example.
Imagine an e-commerce with two separate services:
Every time a new order comes in, the Orders service calls the Inventory service to check if the product is available, and only then confirms the order to the customer.
These two services don’t share any code. They’re separate codebases, different teams. But they’re highly coupled, because if the Inventory service goes down, the Orders service stops working right along with it.
This is an example of coupling at the service level, not the class level. And it’s exactly the kind of thing we miss when we only think about coupling at the code level.
To understand this “beyond” better, Mark Richards splits coupling into two types: static and dynamic.
Static coupling is about structural dependencies, meaning things that exist regardless of whether the system is running or not. It’s the kind of coupling you see by looking at the architecture, not the behavior.
A classic example is a shared database. Imagine our e-commerce’s Orders and Reports services both access the same orders table in the database.
# order service
class OrderService
def order_total(order_id)
Order.where(id: order_id).sum(:value)
end
end
# revenue report service
class RevenueReport
def monthly_revenue
Order.where("created_at >= ?", 30.days.ago).sum(:value)
end
end
The two services never call each other directly. But if the value column gets renamed to total_value, both break. The dependency isn’t in one calling the other’s code, it’s in the shared database structure.
Another place this shows up a lot is inside a Rails monolith, when modules from different domains access each other’s models directly.
# billing module directly accessing the user model
class BillingService
def generate_invoice(user_id)
user = User.find(user_id)
address = user.profile.billing_address
Invoice.create!(user: user, address: address)
end
end
BillingService knows that User has a Profile, and that this profile has a billing_address. If the internal structure of User or Profile changes, the billing module feels it, even though it’s a completely different domain.
Dynamic coupling happens when two components need to be available at the same time for the system to work.
This is exactly the example we saw earlier: the Orders service calling the Inventory service synchronously. If Inventory is down, Orders gets stuck right along with it, because it needs an immediate response to continue.
# order service
class OrdersController < ApplicationController
def create
# if InventoryService doesn't respond, this line fails
available = InventoryService.check_stock(params[:product_id])
return render json: { error: "Out of stock" }, status: 422 unless available
Order.create!(order_params)
end
end
There’s nothing wrong with the code itself. The problem is architectural: a synchronous call creates a time dependency between the two services. If one goes down, the other feels it.
And this kind of coupling doesn’t only show up in HTTP calls. Scheduled jobs suffer from it too, let’s look at another example.
# job that aggregates sales data (runs at midnight)
class AggregateSalesJob < ApplicationJob
def perform
Sale.where("created_at >= ?", 1.day.ago).each { |sale| SalesReport.aggregate(sale) }
end
end
# job that emails the report (runs at 00:30)
class SendDailyReportJob < ApplicationJob
def perform
report = SalesReport.daily_summary
ReportMailer.daily(report).deliver_now
end
end
If AggregateSalesJob takes longer than 30 minutes, SendDailyReportJob fires with incomplete data. Neither job calls the other, but they’re coupled through timing.
Now that we understand what coupling is and how it shows up, it’s worth talking about how to reduce it.
But it’s worth making clear that the goal isn’t zero coupling. Every system has, and needs, some coupling, otherwise components wouldn’t even talk to each other. What we want is to avoid unnecessary coupling.
The answer depends on the type of coupling, so let’s look at each one separately.
For dynamic coupling, a common approach is to swap the synchronous call for asynchronous communication. Instead of waiting for a response from Inventory to confirm the order, the Orders service publishes an event and moves on.
# before: synchronous, dynamic coupling
def create
available = InventoryService.check_stock(params[:product_id])
return render json: { error: "Out of stock" }, status: 422 unless available
Order.create!(order_params)
end
# after: asynchronous, no dynamic coupling
def create
order = Order.create!(order_params.merge(status: :pending))
OrderCreatedEvent.publish(order_id: order.id, product_id: params[:product_id])
render json: order, status: :created
end
The order is created with a pending status and an event gets published. The Inventory service listens for that event and processes it when it can. If Inventory is down, Orders doesn’t even know, and doesn’t need to know.
For static coupling, the idea is to keep a component from navigating another component’s internal structure. This is where the Law of Demeter comes in.
The Law of Demeter says an object should only talk to its direct neighbors, without navigating through the structure of other objects.
Direct neighbors are what the object knows firsthand: itself, the parameters it receives, and the objects it created or already holds as an attribute.
Navigating, in this context, means leaving one object and crossing through others to get where you want.
When you write order.customer.address.city, you’re navigating: you start at order, pass through customer, pass through address, and only then reach city. Each point is a different object being crossed.
Let’s look at an example.
Imagine an InvoiceService that needs the customer’s city to calculate tax:
class InvoiceService
def generate(order)
city = order.customer.address.city
tax_rate = TaxCalculator.rate_for(city)
# ...
end
end
The problem here is that InvoiceService knows Order has a Customer, which has an Address, which has a city. It’s coupled to that whole chain.
If the structure of Address changes, for example if the city moves into a Location object, InvoiceService breaks even though it has nothing to do with that model.
One possible solution is to make Order expose only what the outside needs to know. In Rails, we do that with delegate:
class Order < ApplicationRecord
belongs_to :customer
delegate :city, to: :shipping_address, prefix: :shipping
def shipping_address
customer.address
end
end
class InvoiceService
def generate(order)
tax_rate = TaxCalculator.rate_for(order.shipping_city)
# ...
end
end
Now InvoiceService only knows about Order. If Address changes internally, only Order needs to be updated. The coupling stays contained in the right place.
Isolating this kind of logic in a dedicated object, like a service object, is another common way to contain this coupling.
It’s not an absolute rule, but it’s a good sign that a component knows too much about another one’s internal structure.
At the core, the idea is this: each object hides its own structure and exposes only what’s needed. Whoever’s outside doesn’t need to know how things are organized internally, right?
So, we’ve now got a bit of an understanding of how coupling works. It’s one of those concepts that seems simple in its definition, but gets more interesting the more you start seeing it at different levels.
And keep in mind I only covered a few examples of coupling, because the truth is it can show up in code in a lot of different ways.
If you want to know how automated tools help protect the application from this kind of problem on an ongoing basis, I wrote a post about static analysis.
Well, I hope this helped you understand a bit more about this topic.
See you next time!
]]>The idea is that an application’s architecture shouldn’t depend only on devs remembering it, or on documentation that often only gets read during onboarding. The architecture needs to be validated continuously, and fitness functions help with exactly that.
But something important is that a fitness function isn’t a specific tool, it’s an architectural concept that can be applied in a lot of different ways.
Static analysis tools, automated tests, CI/CD pipelines, observability, and monitoring can all be used as ways to implement fitness functions in practice, as long as they’re continuously validating some important rule or architectural characteristic of the application.
So what I want to explore in this post is one of these forms of application: static analysis.
Static analysis is a technique that involves analyzing code without running the application. That means we’re not going to boot the server, run requests, click on something in the interface, or execute any real system flow.
The analysis happens directly on the source code, and it tries to identify patterns, risks, and problems that can be detected even before the application runs.
Depending on the tool, this can involve complexity analysis, dependencies between modules, security vulnerabilities, project conventions, improper coupling, and other issues related to the system’s structure.
In practice, static analysis can be used to detect things like dead code, unused variables, high complexity, vulnerabilities, forbidden dependencies between parts of the application, convention breaks, and several other types of problems.
Let’s look at an example:
class OrdersController < ApplicationController
def index
if params[:status].present?
@orders = Order.where("status = '#{params[:status]}'")
else
@orders = Order.all
end
if params[:user_id].present?
@orders = @orders.where(user_id: params[:user_id])
end
@orders = @orders.order("created_at #{params[:direction]}")
end
end
Reading this code, a static analysis tool could already raise a few points of attention.
The first problem is in how the query gets built:
Order.where("status = '#{params[:status]}'")
Since the value comes straight from params, there’s a risk of SQL Injection. A tool like Brakeman could flag this snippet as vulnerable, because the application is interpolating external input directly inside a SQL query.
A similar point shows up in the order:
@orders.order("created_at #{params[:direction]}")
Here too, user input directly influences the query. Even if the intention is to only allow asc or desc, the code doesn’t guarantee that. The safer approach would be to explicitly validate which values are allowed before using that parameter.
Besides the security side, a tool like RuboCop could also complain about the method’s complexity. index starts out simple, but it already has conditionals, query building, and filtering rules all in the same place. In a real case, this kind of method tends to grow with more filters, more ordering, and more permission rules.
This example shows something important: static analysis doesn’t need to execute the flow to notice risks. It can look at the code’s structure and identify patterns that usually indicate a problem, like external input used in a query, methods growing too much, or mixed responsibilities in the controller.
Something that started catching my attention while studying static analysis is that it doesn’t try to solve just one type of problem.
Before studying this, I had a pretty simplified view that tools like this were basically for “standardizing code” or complaining about style. But in practice, there are different tools trying to protect completely different things inside the system.
There are tools more focused on consistency and project conventions, others focused on security vulnerabilities, and others trying to control complexity or improper coupling between modules of the application.
That’s where things got more interesting: static analysis goes way beyond linting.
In Rails applications, for example, one tool might try to identify SQL Injection risk without running the application, while another might analyze whether certain modules are coupling in a way the team decided to avoid architecturally.
Different tools end up protecting different characteristics of the system.
When I started researching static analysis in the Ruby/Rails ecosystem more, a few tools kept showing up constantly. But what caught my attention was that they don’t try to solve the same kind of problem.
Each of them seems to focus on protecting a different characteristic of the application.
One of the best known tools in the Ruby ecosystem is RuboCop.
At first, it’s common to associate RuboCop only with code standardization, like single or double quotes, line length, spacing, and writing conventions. And that really is part of its role.
But RuboCop goes beyond that. It can also spot problems related to code complexity and maintainability.
For example, imagine a method like this:
def process_order(order)
if order.paid?
if order.items.any?
if order.customer.active?
send_confirmation_email(order)
update_inventory(order)
notify_analytics(order)
else
cancel_order(order)
end
else
mark_as_invalid(order)
end
else
send_payment_reminder(order)
end
end
Even without running this code, a tool like RuboCop could point out that this method has a lot of complexity, a lot of possible paths, and too many responsibilities concentrated in the same place, a sign that this method is violating the single responsibility principle.
The problem here isn’t just “the code looks ugly.” Methods like this tend to be harder to test, harder to change, and easier to break when a new business rule shows up.
In that sense, RuboCop can help protect an important architectural characteristic: maintainability.
It doesn’t guarantee the application’s architecture is good, but it can work as a warning sign when parts of the code start growing too much or piling up responsibilities.
Brakeman goes in a different direction. Instead of looking at complexity or conventions, it tries to identify security vulnerabilities in the application.
An example:
User.where(“email = '#{params[:email]}'”)
This snippet, interpolating params straight into the query, is a classic SQL Injection pattern. Brakeman can identify this without needing to run the system, just by reading the code’s structure.
Another type of vulnerability Brakeman also detects is XSS, and a common example in Rails shows up with html_safe:
def show
render html: params[:message].html_safe
end
html_safe is a way of telling Rails “you can trust this string, no need to escape it.” By default, Rails escapes any content before rendering it in the browser precisely to avoid this. When you use html_safe on a params value, anything the user sends gets rendered straight into the page, including scripts. This opens the door to XSS, which is when someone manages to inject and execute code in someone else’s browser.
Brakeman flags this pattern because the combination of html_safe with external input is a clear sign of risk.
This was what started making it clearer to me that static analysis has a lot more to do with reducing risk than with standardizing code, and that it connects directly to architectural characteristics like security and reliability.
One of the tools that caught my attention the most while studying this topic was Packwerk.
While tools like RuboCop and Brakeman analyze code quality and security more, Packwerk tries to solve a more architectural problem: controlling dependencies between parts of the application.
Its idea is to let you create boundaries inside a Rails monolith, defining which parts of the system can or can’t depend on each other.
This might seem like overkill at first, but in large applications it’s pretty common for the application’s modules to start coupling more and more over time.
For example:
At first this might seem like just a small shortcut. But as the system grows, these dependencies start making the application harder to change, test, and evolve.
What Packwerk does is turn these architectural rules into automated checks.
In other words, instead of the architecture depending only on documentation or code review, the tool itself can warn when certain dependencies considered invalid start showing up inside the system.
There are plenty of other tools besides these. But looking at RuboCop, Brakeman, and Packwerk together, what stands out is that each one is trying to stop a different type of problem from silently growing inside the application, whether that’s complexity, vulnerabilities, or improper coupling.
When I started studying this topic, I thought static analysis was basically a style tool. What I didn’t expect is that it would be one of the most practical ways to make an application’s architecture stop living only in the team’s head and start being verified automatically.
It’s not about picking the right tool. It’s about deciding which characteristics of the application need to be protected, and making sure that protection happens continuously, not just during code review or in documentation.
]]>If you’ve ever coded in Rails, especially on a large project, you’ve probably already run into them.
Let’s get into it!
Service objects are essentially objects that encapsulate a certain piece of business logic, with the goal of removing complexity from models and controllers.
Usually these objects perform just a single action (process), which keeps you from piling more procedures into other files.
Let me give you an example.
Imagine a simple feature: completing an order in an e-commerce app.
At first glance, it seems simple. The user clicks “checkout” and that’s it. But behind that button, a bunch of things can happen:
Now comes the important question: where should this logic live?
In the controller? In the model?
In small applications, you might see all of this in a single place, usually the model.
Does it work? Yes.
The problem is that, over time, this class ends up with too many responsibilities. Small changes to one rule end up affecting behaviors that have nothing directly to do with each other.
On top of that, it makes the code harder to maintain and test each part.
This is where a service object comes in, as an object responsible for representing that specific process: completing an order.
Instead of spreading this logic across the controller and the model, the service object centralizes that flow in a single place, leaving each part of the application with a clear responsibility.
The controller just orchestrates the request. The model handles the entity’s rules, and the service object coordinates the business logic involved in the process.
Cool? Now let’s understand how this works in practice.
Well, I’ll go ahead and tell you that in Rails a service object is nothing more than a regular Ruby class, but one created with the goal of executing one very specific process.
There’s no official Rails convention specifically for Service Objects, especially since MVC architecture only separates things into models, views, and controllers.
Service objects end up being a way to expand the business layer once it starts growing beyond what the model can hold. If you want to understand better how this layered organization works, check out this post about layered architecture.
But back to the topic, you’ll find that the community has settled on a few practices.
The most common place to put service objects is app/services. But keep in mind you might see other conventions depending on the company you’re working at.
Also, to avoid naming confusion, the community usually follows a few simple patterns.
Generally, service objects have names that clearly represent the action they perform, usually using a verb in the class name. For example:
CreateUserAccountSendWelcomeEmailCompleteOrderThe idea here isn’t to create a rigid rule, but to make the code easier to read. When someone sees this name, they already know exactly what that object does, without needing to open the implementation.
NOTE: worth repeating again that this isn’t “set in stone”, meaning you can, and probably will, run into other kinds of structures and conventions.
Well, considering a service object is meant to carry out just one piece of business logic in isolation, its structure doesn’t need to be very complex.
As I mentioned before, it’s usually just a regular Ruby class.
Beyond that, it usually exposes only one public method, commonly called call, but sometimes it can also be perform, just remember it’s really more of a naming convention.
With this, every time we need to call the service, we just need to call the class and the method.
A simple example of a service object structure in Rails could look something like this:
class CompleteOrder
def initialize(order)
@order = order
end
def call
return false unless order.open?
process_payment
update_order_status
send_confirmation_email
true
end
private
attr_reader :order
def process_payment
# payment logic
end
def update_order_status
order.update!(status: :completed)
end
def send_confirmation_email
# email sending
end
end
Notice this service object only has one action: completing the order.
It’s going to receive the data it needs in initialize, and the only exposed method is call, which is responsible for organizing and calling all the other methods to orchestrate the flow.
And notice it doesn’t replace the model or the controller either.
The service object just coordinates the business logic for that specific process.
So, whenever we need to call this service, the controller would only have this one responsibility, and handling the result:
class OrdersController < ApplicationController
def complete
# Assuming @order was loaded correctly
if CompleteOrder.new(@order).call
redirect_to @order, notice: "Order completed successfully"
else
redirect_to @order, alert: "Unable to complete the order"
end
end
end
So, the controller just calls CompleteOrder.new(@order).call, and that way, all the order completion logic doesn’t need to stay coupled to the controller, it lives in a separate part, making the code easier to maintain.
Now that we understand the structure and how it’s usually done in Rails, let’s understand when to use it or not.
In general, service objects tend to make more sense when an operation starts involving more than a simple action on a single model.
Think about it with me, if creating a user in the application just requires saving some data to the database, a simple User.create already solves the problem.
Now, let’s imagine the flow starts growing, and now you need to:
Notice how the flow grew? All of this couldn’t stay in the model and controller, it won’t be simple to maintain.
Look at how this controller could end up looking with all of that:
class UsersController < ApplicationController
def create
user = User.new(user_params)
if EmailBlocklist.include?(user.email)
redirect_to new_user_path, alert: "Email blocked"
return
end
user.save!
user.create_profile
user.organizations << current_organization
WelcomeEmailJob.perform_later(user.id)
ExternalApiNotifier.notify_user_created(user)
redirect_to user_path(user), notice: "User created successfully"
end
end
You can tell right away that this controller isn’t just orchestrating the user creation request, it’s also concentrating all the business rules and integrations.
And here’s an important point… would this code work? Yes! But it would be hard to test and maintain.
Some signs that it’s time to use a service object: the controller starts growing with logic that isn’t its responsibility, the same rule starts showing up in different places (controllers, jobs, callbacks), or the model starts concentrating behaviors that have nothing to do with the entity itself.
Something that helps me a lot is trying to explain a given model or controller out loud to myself. Explaining code is always useful for understanding better what it’s doing, and if there’s too much stuff inside a controller or model that goes beyond their responsibility, that’s already a sign.
Even though they’re very useful, service objects don’t need to be used in every scenario.
Simple CRUD operations, validations that belong to the model, filters that a scope already solves… in these cases, creating a service object just adds unnecessary complexity. The extraction only makes sense when it makes the code easier to understand, not when it’s done out of habit or to “look more organized.”
A concrete example of when not to use one is when the logic clearly belongs to the model itself.
Imagine a simple user model with a validation and a small behavior:
class User < ApplicationRecord
validates :email, presence: true, uniqueness: true
def active?
status == "active"
end
end
See, in this case, it doesn’t make sense to pull this logic out into a service object, because the validation and the active? method are directly about the state of the data, which in this case is a behavior of the User entity.
See the difference?
Let’s look at an example in the controller:
class UsersController < ApplicationController
def create
user = User.new(user_params)
if user.save
redirect_to user_path(user), notice: "User created successfully"
else
render :new
end
end
private
def user_params
params.require(:user).permit(:email, :name)
end
end
In this case, the controller is doing exactly what’s expected of it: receiving the request, creating the record in the database using the model, and handling the response.
So, keep in mind that service objects aren’t a mandatory rule or pattern. They exist to help organize business logic once complexity starts growing.
At the end of the day, the question isn’t “can I use a service object here?”, but rather “does this actually make the code clearer?”.
It’s not something to use to make the code look pretty or to replace models or controllers, they exist to help when the logic starts growing and it gets hard to understand where each responsibility should live.
I hope this helped you understand this pattern better, because you’ll definitely run into it in large applications.
See you next time!
]]>