Be wary of organizational debt

August 1, 2022

I love legacy code.

As a contractor I spent a lot of time debugging and making sense of code that somebody else created. It's frustrating work, but it also shows you something that greenfield projects don't have (yet).

Any organization that designs a system (defined broadly) will produce a design whose structure is a copy of the organization's communication structure.

— Melvin E. Conway

The above statement is referred to as Conway's law. This law can ruin organizations, frustrate developers and make code harder to maintain.

The biggest danger of Conway's law is that it's not contained in the code. The codebase is the side effect, the cause is the organization itself.

Communication structures

An organization is a group of people trying to work together. Working together means communicating. The business person talks to the sales person who talks to the product person who talks to the engineer person who talks to the sales person who talks to the support person who talks to the customer. Everybody does their own work, but to work together they communicate. Some organizations write tickets, others have gentle taps on the shoulder, some communicate by not communicating.

This communication process gets slowly replaced by the system in question and that structure gets transferred into code. That's how Conway's law works in practice.

How does Conway's law feel like?

There's a funny thing that happens when you're working on mature codebases. You see that technical debt as the easiest one to spot and to fix. There are a lot of improper separation of concerns, functions that have twenty or more parameters, and hardcoded magic variables scattered around the codebase. Don't get me wrong, it's technical debt, and frustrating to fix, but most of the problems are evident and can be fixed in code.

But organizational debt is different. The codebase starts to feel weird. It's not a single thing that's wrong, but a million little things that are just off... It takes some time and talking to loads of people to realise why it feels weird.

Some examples:

Sometimes the naming prefixes are customer, other times they use either client or user. You realise that the naming of the functions are tied to the department from where the work ticket came out of. Customers were from the sales team, users from the customer support and clients were a mix of accounting and the business team. They were all referring to the same thing.

Sometimes there are hacks that bypass the standard order of things, because the business team wanted to make an exception for a certain client, but only in some specific cases. The hack itself isn't that problematic (it's documented and tested), but the business team doesn't even know for which client that exception was (the dev team does know), and if it's still needed. The business person who managed that exception is long gone.

Sometimes there are actual modules and pieces of code that are really hard to work with. The rest of the engineers don't want to touch it, as it's broken and nobody knows what it does. It's convoluted, complex and brittle.

After a while you realise that module pertains to the work of a certain department inside the organization that has issues (you know, a bad manager), and fixing that module would entail actually talking to that department, and it's just not worth the hassle. It's easier to support a broken module than to fix a broken department.

There's a lot of those little examples littered around your codebase. If you're the maintainer of such a legacy project, you're actually blind to all of this weird stuff, because you're a part of the Conway's law. You're one of the causes of it. How you communicate and reason with other people in your organization (not just other engineers, but other departments), is how you'll write code. How you'll structure the system. It's you. You're the problem.

Conway's law cannot be fixed by code or in code. If you want to have meaningful changes to your legacy setup, you have to change the organization. You have to change how the whole organization operates.