The Code Is the Curriculum

I lead a team that builds financial recordkeeping software, and a new engineer can take up to a year to get up to speed. They pick up small pieces here and there, but new concepts do not come across intuitively. There is a sense of unease whenever you are handed something new, because of the financial ramifications of not understanding it completely, and often there are only one or two people who really know it. New features take expertise so you don't break old things. Support tickets take expertise so you don't introduce bad data trying to fix other bad data. The learning feels like repeated cliffs to climb. It is a constant pervasive undertone accepted by the team.

Our org is exploring domain-driven design, so I have been reading Vernon's book to understand it. Two chapters in, it has mostly handed me names for those cliffs. The question I keep circling: are the current systems hard to learn because the domain is massive, or because of how they are designed?

Where engineers actually learn the domain

When a new engineer joins, they are pointed at a small story and the part of the code base it touches. They need their hand held through that first piece, because they are establishing a frame of reference. That seems fine, until it is needed for essentially everything. You master one thing and it does not connect strongly to the next.

I learned this domain by being here six years and picking things up here and there. I never actually learned it from the code. It was better to listen to the domain experts and keep notes I could search later, and I watch most people here end up learning the same way. The code is the source of truth, but one section of it will hardly tell you its wider impact.

Anemic models

Vernon has a name for part of the reason. Anemic models are objects that do not have substance but appear as if they do. The classic example is creating tons of POJOs and using them as the equivalent of database models. Most of us were taught in the MVC pattern to keep the models bare bones while the service classes act on them, so the classes become nothing but their fields, getters, and setters. They do not represent the domain they serve; they only store data. A non-anemic class stands on its own. Someone new should not have to trace every place it is used across the code base to understand what it means to the business.

Vernon opens with a two-question test: are your domain objects mostly getters and setters, and does your business logic live in service classes that operate on them? In our case, it was yes to both. In fact, I would wager that most developers working with MVC would say the same.

What the code teaches

That is where anemia becomes an onboarding problem. Vernon describes a publisher with a single Book class shared by editorial, marketing, and production. Each group means something different by "book," but the code gives them one generic representation. A new engineer reading that class sees common data before the distinctions each group depends on.

When code compresses several business concepts into one technical shape, it teaches new engineers that those concepts are the same. They have to recover the missing distinctions from tickets, conversations, and the few people who already understand them. The code may run correctly while teaching the domain badly.