Productive

Phoenix makes programmers productive. Right out of the box, Phoenix gives you everything you’d expect from a web framework:

• A base architecture for your application
• A database access and management library for connecting to databases
• A routing layer for connecting web requests to your code
• A templating language and helpers for you to write HTML
• Flexible and performant JSON encoding and decoding for external APIs
• Internationalization strategies for taking your application to the world
• All the breadth and power behind Erlang and Elixir so you can grow

Like all web frameworks, Phoenix provides a good cross section of features as functions so users don’t have to code their own. However, features are not enough.

Productivity vs. Maintainability

All framework designers must walk a tightrope. Frameworks must anticipate change by allowing customization, but presenting customization options introduces complexity. Each new feature simply makes the high wire act more treacherous. Let’s call one side of the line productivity and the other maintainability.

When developers have to learn too much too soon, they must slow down to absorb information. One way to keep developers productive early on is hiding details. When a framework designer leans too far this way, developers must pay a price because at some point, the framework will hide information their users need to solve a critical problem. Unusual customizations lead to hours of tedious searching for some mystery incantation to make things work.

Use such a framework long enough and you’ll inevitably make changes that cause your application to drift away from the designers’ intentions, setting yourself up for an eternal upstream battle against the framework. Whether it’s a conflicting upgrade or an optimization that isn’t compatible with your change doesn’t matter. The framework developer’s desire for short-term productivity has cost users long-term maintainability. You can find plenty of stale issues inside the issue trackers for both private and commercial web frameworks, telling this tale with stark clarity.

Sometimes, understanding this limitation, framework designers lean too far in the opposite direction. Too many options in too many places can also have rippling consequences. Options presented in the wrong way force users to make early uninformed decisions. Crippling detail work slowly starves users of the time they need at the beginning of a project, when productivity is the most important.

Phoenix takes a slightly different approach as it walks this tightrope. Phoenix is an opinionated framework that favors convention over configuration. But rather than hiding complexity, it layers complexity, providing details piece by piece.

Phoenix lets users see exactly what’s happening by providing an explicit list of every bit of code a specific route will invoke, one after another. Phoenix hides details in layers by breaking its functionality into small functions and modules and naming them well so they can tell the story. Every application using Phoenix has an endpoint that looks like this:

We are going to dive deep into the mechanics later in the book. For now, what matters is that we have an overview of what our web application provides at a high level.

Rather than forcing users to configure the server with thousands of tiny decisions, Phoenix provides a default outline. If all you want to do is peek under the hood, you can open up a file. You don’t need to modify this base outline at all, but when it’s time to make that obscure change, you can edit this outline to your heart’s content.

So often, productivity means avoiding blocks, and that means developers must have adequate information. Couple the layered architecture with Elixir’s fantastic tools for documentation and you have the tools to be quite productive. For example, you can learn more about any of the components above by simply typing h Plug.Session in your Elixir terminal, or by accessing the documentation online^[2] or directly in your favorite editor.

At the end of the day, Phoenix wants to optimize both productivity and maintainability. After all, maintainability means productivity over time.

Functional Programming 101: Immutability

One of the secrets for Phoenix’s long-term productivity comes from a trait shared across many functional programming languages: immutability.

Imagine the following code:

In most programming languages, you cannot assert with a 100% guarantee the list will still be [1, 2, 3] after calling do_something. That’s because do_something can change the list in place. In Elixir, that’s simply not possible. Our data structures are immutable, so instead of changing the list, we can only build new lists. Therefore our code is written as a series of small functions that receive everything they have to work with as input and return everything they have changed.

This plays a very important role in code readability and maintainability. You will spend much less time and brain cycles trying to figure out what object changed what or what is the current state of a certain component.

While this is a small example, you will find working with Elixir and functional programming to be full of small changes and improvements that make your code easier to understand, both for your teammates and your future self.