Design de Código

Quando Usar

Use quando este fluxo de trabalho corresponder à solicitação do usuário: Vocabulário compartilhado para projetar módulos profundos. Use quando o usuário quiser projetar ou melhorar a interface de um módulo, encontrar oportunidades de aprofundamento, decidir onde uma emenda vai, tornar o código mais testável ou navegável por IA, ou quando outra habilidade precisar do vocabulário de módulo profundo.

Fonte: mattpocock/skills (MIT).

Projete módulos profundos: muita funcionalidade por trás de uma interface pequena, posicionados em uma emenda limpa, testáveis através dessa interface. Use esta linguagem e estes princípios onde quer que o código esteja sendo projetado ou reestruturado. O objetivo é alavancagem para os chamadores, localidade para os mantenedores e testabilidade para todos.

Glossário

Use estes termos exatamente — não substitua "componente", "serviço", "API" ou "limite". A linguagem consistente é o ponto principal.

Módulo — qualquer coisa com uma interface e uma implementação. Deliberadamente agnóstico à escala: uma função, classe, pacote ou fatia que abrange camadas. Evite: unidade, componente, serviço.

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

Implementação — o que está dentro de um módulo, seu corpo de código. Distinto de Adaptador: uma coisa pode ser um pequeno adaptador com uma grande implementação (um repositório Postgres) ou um grande adaptador com uma pequena implementação (um fake em memória). Use "adaptador" quando a emenda for o tópico; "implementação" caso contrário.

Profundidade — alavancagem na interface: a quantidade de funcionalidade que um chamador (ou teste) pode exercer por unidade de interface que ele precisa aprender. Um módulo é profundo quando uma grande quantidade de funcionalidade está por trás de uma interface pequena, raso quando a interface é quase tão complexa quanto a implementação.

Emenda (Michael Feathers) — um local onde você pode alterar o comportamento sem editar naquele local; a localização onde a interface de um módulo vive. Onde colocar a emenda é uma decisão de design própria, distinta do que vai por trás dela. Evite: limite (sobrecarregado com o contexto delimitado do DDD).

Adaptador — uma coisa concreta que satisfaz uma interface em uma emenda. Descreve o papel (qual slot preenche), não a substância (o que está dentro).

Alavancagem — o que os chamadores obtêm da profundidade: mais capacidade por unidade de interface que aprendem. Uma implementação retorna em N locais de chamada e M testes.

Localidade — o que os mantenedores obtêm da profundidade: mudança, bugs, conhecimento e verificação se concentram em um local em vez de se espalharem pelos chamadores. Corrija uma vez, corrigido em todos os lugares.

Profundo vs. Raso

Módulo profundo = interface pequena + muita implementação:

┌─────────────────────┐
│   Small Interface   │  ← Few methods, simple params
├─────────────────────┤
│                     │
│  Deep Implementation│  ← Complex logic hidden
│                     │
└─────────────────────┘

Módulo raso = interface grande + pouca implementação (evite):

┌─────────────────────────────────┐
│       Large Interface           │  ← Many methods, complex params
├─────────────────────────────────┤
│  Thin Implementation            │  ← Just passes through
└─────────────────────────────────┘

Ao projetar uma interface, pergunte:

• Posso reduzir o número de métodos?
• Posso simplificar os parâmetros?
• Posso esconder mais complexidade internamente?

Princípios

• A profundidade é uma propriedade da interface, não da implementação. Um módulo profundo pode ser internamente composto de partes pequenas, simuláveis e substituíveis — elas apenas não fazem parte da interface. Um módulo pode ter emendas internas (privadas à sua implementação, usadas por seus próprios testes) bem como a emenda externa em sua interface.
• O teste de exclusão. Imagine excluir o módulo. Se a complexidade desaparecer, foi um passe direto. Se a complexidade reaparecer em N chamadores, ele estava valendo a pena.
• A interface é a superfície de teste. Chamadores e testes cruzam a mesma emenda. Se você quiser testar além da interface, o módulo provavelmente está com o formato errado.
• Um adaptador significa uma emenda hipotética. Dois adaptadores significam uma emenda real. Não introduza uma emenda a menos que algo realmente varie através dela.

Projetando para Testabilidade

Boas interfaces tornam os testes naturais:

1. Aceite dependências, não as crie.

   // Testável
   

…