This post is an excerpt from our e-book Growing Rails Applications in Practice, now available through The Pragmatic Programmers and Leanpub.

---

As a Rails application grows, so does its app/models folder. We've seen applications grow to hundreds of models. With an app/models directory that big, it becomes increasingly hard to navigate. Also it becomes near-impossible to understand what the application is about by looking at the models folder, where the most important models of your core domain sit next to some support class of low significance.

A good way to not drown in a sea of .rb files is to aggressively namespace models into sub-folders. This doesn't actually reduce the number of files of course, but makes it much easier to browse through your model and highlights the important parts.

Namespacing a model is easy. Let's say we have an Invoice class and each invoice can have multiple invoice items:

class Invoice < ActiveRecord::Base
  has_many :items
end

class Item < ActiveRecord::Base
  belongs_to :invoice
end

Clearly Invoice is a composition of Items and an Item cannot live without a containing Invoice. Other classes will probably interact with Invoice and not with Item. So let's get Item out of the way by nesting it into the Invoice namespace. This involves renaming the class to Invoice::Item and moving the source file to app/models/invoice/item.rb:

 class Invoice::Item < ActiveRecord::Base
   belongs_to :invoice
 end

What might seem like a trivial refactoring has great effects a few weeks down the road. It is a nasty habit of Rails teams to avoid creating many classes, as if adding another file was an expensive thing to do. And in fact making a huge models folder even larger is something that does not feel right.

But since the models/invoice folder already existed, your team felt encouraged to create other invoice-related models and place them into this new namespace:

File	Class
app/models/invoice.rb	Invoice
app/models/invoice/item.rb	Invoice::Item
app/models/invoice/reminder.rb	Invoice::Reminder
app/models/invoice/export.rb	Invoice::Export

Note how the namespacing strategy encourages the use of service objects in lieu of fat models that contain more functionality than they should.

Real-world example

In order to visualize the effect that heavy namespacing has on a real-world-project, we refactored one of our oldest applications, which was created in a time when we didn't use namespacing.

Here is the models folder before refactoring:

activity.rb
amortization_cost.rb
api_exchange.rb
api_schema.rb
budget_calculator.rb
budget_rate_budget.rb
budget.rb
budget_template_group.rb
budget_template.rb
business_plan_item.rb
business_plan.rb
company.rb
contact.rb
event.rb
fixed_cost.rb
friction_report.rb
internal_working_cost.rb
invoice_approval_mailer.rb
invoice_approval.rb
invoice_item.rb
invoice.rb
invoice_settings.rb
invoice_template.rb
invoice_template_period.rb
listed_activity_coworkers_summary.rb
note.rb
person.rb
planner_view.rb
profit_report_settings.rb
project_filter.rb
project_link.rb
project_profit_report.rb
project_rate.rb
project.rb
project_summary.rb
project_team_member.rb
project_type.rb
rate_group.rb
rate.rb
revenue_report.rb
review_project.rb
review.rb
staff_cost.rb
stopwatch.rb
task.rb
team_member.rb
third_party_cost.rb
third_party_cost_report.rb
topix.rb
user.rb
variable_cost.rb
various_earning.rb
workload_report.rb

Looking at the huge list of files, could you tell what the application is about? Probably not (it's a project management and invoicing tool).

Let's look at the refactored version:

/activity
/api
/contact
/invoice
/planner
/report
/project
activity.rb
contact.rb
planner.rb
invoice.rb
project.rb
user.rb

Note how the app/models folder now gives you an overview of the core domain at one glance. Every single file is still there, but neatly organized into a clear directory structure. If we asked a new developer to change the way invoices work, she would probably find her way through the code more easily.

Use the same structure everywhere

In a typical Rails application there are many places that are (most of the time) structured like the models folder. For instance, you often see helper modules or unit tests named after your models.

When you start using namespaces, make sure that namespacing is also adopted in all the other places that are organized by model. This way you get the benefit of better organization and discoverability in all parts of your application.

Let's say we have a namespaced model Project::Report. We should now namespace helpers, controllers and views in the same fashion:

File	Class
app/models/project/report.rb	Project::Report
app/helpers/project/report_helper.rb	Project::ReportHelper
app/controllers/projects/reports_controller.rb	Projects::ReportsController
app/views/projects/reports/show.html.erb	View template

Note how we put the controller into a Projects (plural) namespace. While this might feel strange at first, it allows for natural nesting of folders in in app/views:

app/
  views/
    projects/
      index.html.erb
      show.html.erb
      reports/
        show.html.erb

If we put the controller into a Project (singular) namespace, Rails would expect view templates in a structure like this:

app/
  views/
    project/
      reports/
        show.html.erb
    projects/
      index.html.erb
      show.html.erb

Note how two folders project (singular) and projects (plural) sit right next to each other. This doesn't feel right. We feel that the file organization of our views is more important than keeping controller namespace names in singular form.

Organizing test files

When we have tests we nest the test cases and support code like we nest our models. For instance, when you use RSpec and Cucumber, your test files should be organized like this:

File	Description
spec/models/project/report_spec.rb	Model test
spec/controllers/projects/reports_controller_spec.rb	Controller test
features/project/reports.feature	Cucumber untegration test
features/step_definitions/project/report_steps.rb	Step definitions

Other ways of organizing files

Of course models/controllers/tests don't always map 1:1:1, but often they do. We think it is at the very least a good default with little ambiguity. When you look for a file in a project structured like this, you always know where to look first.

If another way to split up your files feels better, just go ahead and do it. Do not feel forced to be overly consistent, but always have a good default.