Codebase Design

Projete módulos profundos (deep modules): muito comportamento atrás de uma interface pequena, posicionado em um seam limpo, testável através dessa interface. Use esta linguagem e estes princípios sempre que código estiver sendo projetado ou reestruturado. O objetivo é leverage para quem chama, locality para mantenedores e testabilidade para todos.

Glossário

Use estes termos exatamente — não substitua por "component", "service", "API" ou "boundary". Linguagem consistente é o objetivo principal.

Module — qualquer coisa que tenha uma interface e uma implementação. Deliberadamente agnóstico em escala: uma função, classe, pacote ou um slice que atravessa camadas. Evite: unit, component, service.

Interface — tudo que um caller precisa saber para usar o módulo corretamente: a assinatura de tipo, mas também invariantes, restrições de ordenação, modos de erro, configuração necessária e características de performance. Evite: API, signature (muito estreito — referem-se apenas à superfície de tipo).

Implementation — o que está dentro do módulo, seu corpo de código. Diferente de Adapter: uma coisa pode ser um adapter pequeno com uma implementation grande (um repositório Postgres) ou um adapter grande com uma implementation pequena (um fake em memória). Use "adapter" quando o seam for o tema; "implementation" caso contrário.

Depth — leverage na interface: a quantidade de comportamento que um caller (ou teste) consegue exercer por unidade de interface que precisa aprender. Um módulo é deep quando uma grande quantidade de comportamento fica atrás de uma interface pequena, shallow quando a interface é quase tão complexa quanto a implementação.

Seam (Michael Feathers) — um lugar onde você pode alterar comportamento sem editar naquele lugar; a localização onde a interface do módulo vive. Onde colocar o seam é uma decisão de design própria, distinta do que fica atrás dele. Evite: boundary (sobrecarregado com bounded context do DDD).

Adapter — uma coisa concreta que satisfaz uma interface em um seam. Descreve papel (qual slot ele preenche), não substância (o que tem dentro).