Ep 115: The Main Event

Each week, we discuss a different topic about Clojure and functional programming.

If you have a question or topic you'd like us to discuss, tweet @clojuredesign, send an email to feedback@clojuredesign.club, or join the #clojuredesign-podcast channel on the Clojurians Slack.

This week, the topic is: "the main function". We look for a suitable place to dig into the code and find an entry point.

Our discussion includes:

• We're diving into a Clojure project. Where should we start?
• First up: the backend.
• Why start with the code?
• Why is "main" so important?
• What's the problem with lots of entry points?
• What should a good "main" do?
• How does a good "main" help you find things?
• What is a good component system?
• The difficulty of understanding inter-component dependencies.
• What is a "table of contents" for your program?
• Random access reading.
• What are common kinds of components?
• What is a pure model?
• How do pure parts and side-effecting parts all come together?

Selected quotes

Be friendly to people that come into your code base.

I didn't trust myself as much as I should.

"You just start at the top and write from the top to the bottom." "That's how I code everything. It's just one really large file."

So all parts of your code are reachable from "main"—or should be.

A great "main" is where you can see all the major parts of the application and how they fit together with each other.

A terrible "main" is a system that doesn't have any "main" at all! It has a thousand different entry points that are all over the place.

A great "main" is very compact. You can scan it. It's a very high level recipe of what's going on.

Component has a system map. You can just look at the data structure and see all of the different components—the major players.

The alternative is components that declare dependencies on each other. It's a kind of nightmare. Everything running independently, calling or referencing each other. What's using what? What's calling what? How does information flow through?

When dependency information gets spread all over the place, you have to go to all the different places to even understand what you need. Having it all in one place is essential for understanding.

It really helps when you can see the interdependency between things really easily. Each component should only get what it actually needs. It shouldn't just get the whole map of every dependency.

Common kinds of components: shared resources, integrations in, integrations out, pure models, state holders, and amalgamations. It all comes together in the amalgamations.

Pure models are the core of the application. They are higher level than just data manipulation.

All of the actual nuts and bolts is in the pure models, and that makes the components relatively light.

The goal is to make the pure model as fat as possible without introducing any non-determinism, AKA side effects.

Amalgamations: it's where the "in", the "out", and the pure model all come together—where the real work gets done.

The amalgamation components end up being at the middle of the application. They're a kind of orchestrator.

Common kinds of components

• shared resources
• integrations in
• integrations out
• state holders
• pure models
• amalgamations

Links

• Component
• Ep 097: Application of Composition. We discuss having table-of-contents style sections in your code. It helps with finding things and forming the big picture.