Razsk/VideoStudio

Design de Código

Projete módulos profundos: muito comportamento atrás de uma interface pequena, colocada em uma costura limpa, testável por meio dessa interface. Use esta linguagem e esses princípios sempre que o código estiver sendo projetado ou reestruturado. O objetivo é alavancagem para quem chama, localidade para quem mantém e testabilidade para todos.

Glossário

Use estes termos exatamente: não substitua por "componente", "serviço", "API" ou "fronteira". Linguagem consistente é o ponto principal.

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

Interface: tudo o que quem chama 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 desempenho. Evite: API, assinatura (restrito demais, referem-se apenas à superfície de tipo).

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

Profundidade: alavancagem na interface. A quantidade de comportamento que quem chama (ou um teste) pode exercer por unidade de interface que precisa aprender. Um módulo é profundo quando uma grande quantidade de comportamento fica atrás de uma interface pequena, e raso quando a interface é quase tão complexa quanto a implementação.

Costura (Michael Feathers): um lugar onde você pode alterar comportamento sem editar naquele lugar; o local onde a interface de um módulo reside. Onde colocar a costura é uma decisão de design em si, distinta do que fica atrás dela. Evite: fronteira (sobrecarregado com o contexto delimitado de DDD).

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

Alavancagem: o que quem chama obtém da profundidade. Mais capacidade por unidade de interface que aprendem. Uma implementação se paga em N locais de chamada e M testes.

Localidade: o que quem mantém obtém da profundidade. Mudanças, bugs, conhecimento e verificação se concentram em um só lugar, 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:

┌─────────────────────┐
│   Pequena Interface  │  ← Poucos métodos, parâmetros simples
├─────────────────────┤
│                     │
│  Implementação Profunda│  ← Lógica complexa oculta
│                     │
└─────────────────────┘

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

┌─────────────────────────────────┐
│       Grande Interface          │  ← Muitos métodos, parâmetros complexos
├─────────────────────────────────┤
│  Implementação Fina             │  ← Apenas passa adiante
└─────────────────────────────────┘

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

• Profundidade é uma propriedade da interface, não da implementação. Um módulo profundo pode ser internamente composto por partes pequenas, simuláveis e substituíveis; elas simplesmente não fazem parte da interface. Um módulo pode ter costuras internas (privadas à sua implementação, usadas por seus próprios testes), bem como a costura externa em sua interface.
• O teste de exclusão. Imagine deletar o módulo. Se a complexidade desaparecer, era um mero passador. Se a complexidade reaparecer em N chamadores, ele estava ganhando seu espaço.
• A interface é a superfície de teste. Chamadores e testes cruzam a mesma costura. Se você quiser testar além da interface, o módulo provavelmente tem o formato errado.
• Um adaptador significa uma costura hipotética. Dois adaptadores significa uma costura real. Não introduza uma costura a menos que algo realmente varie através dela.

Projetando para testabilidade

Interfaces boas tornam o teste natural:

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

   // Testável
   function processOrder(order, paymentGateway) {}
   
   // Difícil de testar
   function processOrder(order) {
     const gateway = new StripeGateway();
   }
   

2. Retorne resultados, não produza efeitos colaterais.

   // Testável
   function calculateDiscount(cart): Discount {}
   
   // Difícil de testar
   function applyDiscount(cart): void {
     cart.total -= discount;
   }
   

3. Pequena área de superfície. Menos métodos = menos testes necessários. Menos parâmetros = configuração de teste mais simples.

Relacionamentos

• Um Módulo tem exatamente uma Interface (a superfície que apresenta a chamadores e testes).
• Profundidade é uma propriedade de um Módulo, medida contra sua Interface.
• Uma Costura é onde a Interface de um Módulo reside.
• Um Adaptador fica em uma Costura e satisfaz a Interface.
• Profundidade produz Alavancagem para quem chama e Localidade para quem mantém.

Enquadramentos rejeitados

• Profundidade como razão entre linhas de implementação e linhas de interface (Ousterhout): recompensa o enchimento da implementação. Usamos profundidade-como-alavancagem.
• "Interface" como a palavra-chave interface do TypeScript ou métodos públicos de uma classe: restrito demais: interface aqui inclui todo fato que quem chama precisa saber.
• "Fronteira": sobrecarregado com o contexto delimitado de DDD. Diga costura ou interface.

Indo mais fundo

• Aprofundando um cluster dadas suas dependências, veja DEEPENING.md: categorias de dependência, disciplina de costura e teste de substituir-não-camadas.
• Explorando interfaces alternativas, veja DESIGN-IT-TWICE.md: crie subagentes paralelos para projetar a interface de várias maneiras radicalmente diferentes e depois compare com base em profundidade, localidade e posicionamento da costura.