O que é um padrão e como criar um?

Em 2013, o Fabio Akita escreveu um artigo que ficou na minha cabeça por um bom tempo: A Língua Portuguesa-Brasileira é Péssima: Standard vs Pattern. A tese central é simples, mas poderosa: a palavra “padrão” em português mistura dois conceitos distintos em inglês — standard e pattern — e essa confusão afeta como a gente pensa e aplica esses conceitos no dia a dia.

Esse post é uma releitura daquela ideia, com os aprendizados que acumulei depois de alguns anos criando e mantendo padrões em times de desenvolvimento.

Standard vs Pattern

Em inglês, a distinção é clara:

Standard — uma norma. Algo obrigatório, que deve ser seguido sem adaptação. Um padrão de conformidade.
Pattern — um template. Uma solução reutilizável para um problema recorrente, que orienta sem ser prescritivo.

O Gang of Four, que popularizou os Design Patterns nos anos 90, deixou isso explícito na definição original: um design pattern é uma “solução reutilizável geral para um problema comum” — não uma solução fechada que pode ser copiada e colada sem pensar.

Em português, usamos a mesma palavra para os dois: padrão. E isso cria um problema sutil: quando alguém diz “cria um padrão pra isso”, a outra pessoa pode entender “standard” (obrigatório, imutável) quando a intenção era “pattern” (orientação, ponto de partida).

O problema não é a palavra — é o que as pessoas entendem por ela.

Por que isso importa na prática

Quando você cria um padrão como se fosse um standard, cria rigidez desnecessária. O time para de pensar sobre o problema e passa a executar o procedimento — mesmo quando o contexto mudou e o procedimento original não faz mais sentido.

Quando você cria um padrão como um pattern, você está documentando uma solução que funcionou bem e pode ser adaptada. O time usa como referência, não como bíblia.

A diferença entre os dois não é só semântica — ela afeta a cultura do time.

Quando vale a pena escrever um padrão

Minha regra prática: só escreva quando necessário.

Isso pode parecer óbvio, mas na prática a tentação de documentar tudo é real — especialmente em times que acabaram de passar por um problema causado por falta de documentação. A resposta emocional é “vamos documentar para nunca mais deixar isso acontecer”. O resultado costuma ser uma wiki com 200 páginas que ninguém lê.

Documentações têm uma característica ingrata: desatualizam rápido. O código muda, as convenções mudam, o time muda — e a documentação fica para trás silenciosamente, às vezes tornando-se mais prejudicial do que útil por passar confiança errada.

Antes de escrever qualquer padrão, vale perguntar:

Isso vai ser reutilizado várias vezes? Se for algo que acontece uma vez ou raramente, provavelmente não precisa de documentação formal.
Existe uma forma melhor de comunicar isso? Às vezes um comentário no código, uma convenção de nomeação ou um exemplo em código resolvem melhor do que um documento de texto.
Quem vai precisar ler isso? E com que frequência? Se a resposta for “uma pessoa, uma vez”, talvez não valha a pena o esforço de documentar.

O problema humano da documentação

Há um fato incômodo que costumamos ignorar quando criamos documentação: programadores são humanos.

Humanos:

Muitas vezes não leem documentação — especialmente quando estão no meio de um fluxo de trabalho
Quando leem, leem de forma superficial e seletiva
Esquecem o que leram, especialmente se o padrão não for aplicado com frequência

Isso não é crítica a ninguém — é como a atenção humana funciona. A consequência prática é que um padrão precisa ser autoexplicativo e fácil de entender. Se alguém precisa ler três páginas de contexto antes de conseguir aplicar o padrão, ele é muito complexo ou mal escrito.

Um bom padrão é aquele que alguém consegue entender em dois minutos e aplicar na primeira vez sem precisar pedir ajuda.

O custo que ninguém contabiliza

Além do problema da atualização e da leitura, há um custo mais sutil: sobrecarga mental.

Cada regra, cada padrão, cada convenção obrigatória é mais um item que o desenvolvedor precisa manter na cabeça enquanto trabalha. Um time com 50 padrões documentados pode parecer bem organizado no papel — mas pode estar, na prática, criando uma carga cognitiva que diminui a velocidade e a qualidade do trabalho.

Com o uso de IA no dia a dia, isso ganhou uma dimensão nova: vale a pena gastar contexto de uma IA com padrões internos? Dependendo do projeto e da empresa, a resposta pode ser sim — mas esse custo também deve ser considerado. Jogar um documento de 10 páginas como contexto para cada prompt tem um preço.

A regra continua sendo custo-benefício. Menos padrões, mais relevantes, mais curtos.

Como criar um padrão que as pessoas usam de verdade

Se depois de tudo isso você chegou à conclusão de que um padrão é necessário, aqui vai o que aprendi sobre criar documentações que realmente funcionam:

1. Explique o porquê antes do como

Quem vai ler o padrão precisa entender por que ele existe. Sem contexto, a tendência é seguir a forma sem entender a intenção — e aí você tem pessoas seguindo o procedimento quando o contexto já mudou.

2. Inclua exemplos concretos

Nada substitui ver o padrão aplicado. Um exemplo de código, uma estrutura de pasta, um template preenchido — qualquer coisa tangível ajuda mais do que uma descrição abstrata.

3. Diga explicitamente quando não aplicar

Um pattern tem limites. Documentar as exceções e os casos em que o padrão não deve ser seguido é tão importante quanto o padrão em si. Isso evita aplicações mecânicas em contextos errados.

4. Mantenha curto

Se o padrão precisar de mais de uma página para ser explicado, provavelmente está documentando coisa demais em um lugar só. Divida ou simplifique.

5. Revise periodicamente

Coloque uma data de criação e, se possível, uma data de revisão. Documentação sem data é documentação sem validade.

Padrões são bons — com cautela

Para ser direto sobre onde estou nessa discussão: sou a favor de documentar padrões. Times que trabalham com convenções explícitas tendem a ser mais coesos, onboardings são mais rápidos e decisões de arquitetura ficam menos dependentes de uma ou duas pessoas.

Mas a documentação que funciona é a que foi criada com critério. Pouca, relevante, bem escrita e mantida.

Um padrão bom é aquele que libera o time para pensar nos problemas importantes — não aquele que ocupa espaço mental desnecessário ou cria burocracia disfarçada de organização.

Referência: Fabio Akita — “A Língua Portuguesa-Brasileira é Péssima: Standard vs Pattern” (2013)