If you are a web developer, you are probably used to having new frameworks, libraries and technologies come out every other week.

We are on a never-ending quest to find better tools and patterns, but does that mean our code is doomed to become old and wrinkly?

How do you anchor your project so that it resists the Winds of Trend

1. Split your code based on domain concepts, not tech concepts

One of the first questions you may have when starting a new project is how should you structure it. There are two popular schools of thought here: Either we split our files by tech concepts, or by domain concepts.

# Split by tech concepts        # Split by domain concepts

|- src                          |- auth|  |- controllers               |  |- controllers|  |  |- auth                   |  |- models|  |  |- profile                |  |- views|  |  |- article                |  |- tests|  |- models                    |- profile|  |- views                     |- article|- test                         (...)|  |- controllers|  |  |- auth(...)

If you’ve read the header you might have an idea of what we’ll recommend, but let’s back that up with a few thoughts.

Say you arrive at the root of a project with a specific goal (hunting down a bug, adding a feature, removing it, etc.). You need to find the appropriate code, navigate through related files, take a look at the tests, and when you feel confident enough, make those changes to the codebase.

As developers, this process is our bread and butter, so we better make it efficient.

What is easier to maintain, a codebase with 10 files or one with 100 files?

Splitting code by domain concepts allows you to focus on a small part of your codebase, whereas doing it by tech concept forces you to jump around.

2. Provide a public contract (API) for all your domain concepts

Imagine your project has a payments directory where you keep all ?-related code. We have a series of components to store our payments in a database or connect to 3rd-party services like Stripe.

All those components are there to fulfill a contract, that is, to make sure payments behave they way they should.

Just to be clear, we are not talking about the HTTP API your mobile app will call to charge users. We are talking about an internal API that turns your payments directory into its own “microservice” (using the term freely).

Why, you ask?

Because having an explicit API provides:

• A clear picture of the expected behavior.
• A minimum test coverage everyone can agree upon and commit to.
• The freedom to change anything from the underlying implementation.

Furthermore, it is important for this API to know as little as possible of external concepts such as users, permissions or environments. These are not part of the domain. They are the way we solve a problem with the communication layer (a public HTTP endpoint is inherently insecure) or our development workflow.

For instance, we can imagine having:

• A public-facing API that exposes some of the domain behavior and controls authentication and authorization.
• A private admin API + panel to provide easy customer support and look into bugs without ever touching any database or console.
• A really easy way to write fixtures, examples and migrations.

3. Rely on small interfaces

This one is pretty popular. As developers, we are constantly reminded to rely on abstractions instead of concrete implementations, segregate our interfaces and invert our dependencies.

You can easily find plenty of material covering the theory, so let’s focus on some practical examples. Our Payments app might need to talk to these interfaces:

• An event publisher
• An event subscriber
• A credit card charger
• An email sender

All these interfaces have a small and clearly defined role. Later on, we will inject the particular implementations:

production = Payments.new( event_publisher: rabbitmq, event_subscriber: rabbitmq_replicas, credit_card_charger: stripe, email_sender: mailgun,)

development = Payments.new( event_publisher: in_memory_bus, event_subscriber: in_memory_bus, credit_card_charger: stripe_test_mode, email_sender: muted_mailer,)

As you can see, small interfaces allow us to create well-defined tests and choose the best strategy for each action depending on the environment. On the other hand, we usually write implementations based on particular technologies, to centralize all the knowledge and helper functions around them.

4. Decouple your data from your storage strategy

Let’s get it out of the way: We think ORMs are wrong (or maybe it’s people who are doing them wrong). Take a look at this Ruby on Rails code:

class Article < ActiveRecord::Base  belongs_to :user  has_many :comments, dependent: :destroy

  scope :authored_by, ->(username) { where(user: User.where(username: username)) }

  validates :title, presence: true, allow_blank: false  validates :body, presence: true, allow_blank: false

  before_validation do    self.slug ||= “#{title.to_s.parameterize}-#{rand(36**6).to_s(36)}”  endend

There’s a lot to unpack here.

First, we notice this object is describing relationships, cascade deletion and nullable attributes. Exactly what you would expect from an Object-Relational Mapper. Quite transparent!

Next, let’s consider for a moment. What is important for us when representing an Article?:

• We should be able to harness the full power of the language we are using. When we are using Java, we want to be able to use OO patterns and inheritance freely. When we are using Haskell, we want to use union types and records.
• We should be able to store our data in different formats and databases. This allows us to use ElasticSearch for performant searches, PostgreSQL for a consistent state and Redis to keep our autosave feature fast enough.

ORM models offer neither, because they are just a way to interface with a SQL database. We still need to represent and manipulate our data somewhere else. The problem is, once you accept this statement, using an ORM seems awkward or overkill. This is what we mean:

The bottom line here is: You can use ORMs, but don’t use them as the only way to represent and manipulate your data. That’s far from their purpose.

5. Use events to keep your application connected and your code decoupled

If two parts of an application are connected, the code must connected somehow, right?

Event-driven programming does a wonderful job at keeping your app interconnected, but your code easy to write and maintain. In fact it does such a good job that similar ideas have become pervasive in mobile and frontend development under the name of Reactive Programming, and in the operations world, with cloud providers and companies betting hard on it.

The basic idea is that every change to your domain is represented as an atomic event.

article_published(…) 1 minute agoarticle_draft_created(…) 5 minutes agouser_signed_in(…) 25 minutes ago

All events are published through some kind of event bus, and random observers can subscribe and react to interesting events without bothering the other components too much.

It takes a bit of an extra effort at first, as you need to lay the foundation for the event bus and think about the properties and atomicity of each event, but in the long run it’s definitely worth it.

Here are some examples of features that are very easy to implement with event-driven architectures, and hard to think about and maintain otherwise:

• Listen for comments on an article and increase a counter (purpose: faster comment counts).
• Send a welcome email to a new user.
• Notify the author of an article that it has new comments.

Try to imagine how you would do each of these tasks in an imperative way vs. a reactive way.

Event-driven programming avoids long functions with many different side effects, and makes your tests nicer and more isolated.