Pular para o conteúdo
Clean Code

Comunicação em Equipe

Escrever código é apenas uma parte do trabalho em equipe. Em ambientes profissionais, boa parte da qualidade do software depende da capacidade de comunicar intenção, contexto, risco, decisão e impacto de mudança.

Isso aparece em artefatos como pull requests, revisões, decisões arquiteturais e documentação do repositório. Quando esses mecanismos são fracos, o time passa a depender de memória oral, mensagens soltas e conhecimento tácito. Quando são fortes, o projeto ganha rastreabilidade, previsibilidade e mais facilidade para evoluir.

Introdução

Seção intitulada “Introdução”

Muita gente aprende colaboração como uma sequência de comandos de Git: criar branch, fazer commit, abrir PR, resolver conflito. Isso é necessário, mas está longe de ser suficiente.

Em um time maduro, colaboração não é apenas sincronizar arquivos. É tornar mudanças compreensíveis para outras pessoas.

Isso envolve perguntas como:

  • por que essa alteração existe?
  • qual problema ela resolve?
  • que risco introduz?
  • como deve ser validada?
  • que decisão de design ou arquitetura está embutida nela?
  • que documentação precisa ser atualizada junto com o código?

Comunicação é infraestrutura de qualidade

Seção intitulada “Comunicação é infraestrutura de qualidade”

É comum pensar em comunicação como algo periférico, quase uma “soft skill” separada da engenharia. Na prática, ela faz parte da própria infraestrutura de qualidade do software.

Sem comunicação técnica clara, o time sofre com:

  • revisões lentas e superficiais;
  • retrabalho por mal-entendido;
  • decisões arquiteturais repetidamente rediscutidas;
  • onboarding demorado;
  • dependência excessiva de pessoas específicas;
  • documentação desatualizada ou impossível de encontrar.

Boa comunicação reduz custo futuro de mudança. Ela transforma conhecimento individual em contexto compartilhado.

Pull Request é um artefato de comunicação

Seção intitulada “Pull Request é um artefato de comunicação”

Uma pull request ou merge request não deve ser tratada como simples botão de merge. Ela é o principal artefato de conversa técnica sobre uma mudança antes da integração.

Uma boa PR ajuda o time a entender:

  • o que mudou;
  • por que mudou;
  • como validar a mudança;
  • que partes do sistema foram afetadas;
  • que riscos ou trade-offs existem.

Quando a PR não comunica isso, o revisor passa a reconstruir contexto sozinho a partir do diff. Isso torna a revisão mais lenta, menos precisa e mais cansativa.

PRs pequenas são melhores

Seção intitulada “PRs pequenas são melhores”

Guias de engenharia como os do Google reforçam uma prática importante: mudanças pequenas e autocontidas tendem a ser revisadas mais rapidamente e com mais qualidade.

PRs pequenas são melhores porque:

  • exigem menos carga cognitiva do revisor;
  • reduzem a chance de bugs passarem despercebidos;
  • facilitam testes e rollback;
  • geram menos conflito de merge;
  • permitem feedback mais cedo.

O ideal não é “dividir por número de linhas” de forma cega, mas manter uma mudança focada em uma intenção coerente. Misturar refatoração, correção, documentação, estilo e funcionalidade nova na mesma PR geralmente piora a revisão.

O que uma boa PR deve conter

Seção intitulada “O que uma boa PR deve conter”

Uma boa PR normalmente inclui:

  • título claro;
  • descrição resumindo contexto e motivação;
  • vínculo com issue, ticket ou demanda quando existir;
  • explicação de impacto e risco;
  • passos de teste ou evidência de validação;
  • screenshots ou vídeos curtos, quando a mudança é visual;
  • menção explícita a documentação atualizada, quando aplicável.

Em outras palavras, a PR deve reduzir o esforço necessário para alguém entender e confiar na mudança.

Draft PR e feedback cedo

Seção intitulada “Draft PR e feedback cedo”

Esperar “ficar perfeito” para abrir PR pode atrasar feedback importante. Em muitos times, abrir uma draft PR cedo é uma prática saudável.

Isso ajuda a:

  • alinhar direção técnica antes de investir demais;
  • sinalizar trabalho em andamento;
  • obter feedback arquitetural ou de produto antes da finalização;
  • reduzir risco de rejeição tardia.

Uma draft PR não substitui cuidado com qualidade, mas permite revisão incremental de mudanças maiores.

Code Review não é caça a erro de estilo

Seção intitulada “Code Review não é caça a erro de estilo”

Revisão de código não serve apenas para encontrar erro sintático ou discutir preferência pessoal. Guias maduros de review, como os do Google, tratam revisão como avaliação técnica mais ampla.

Uma boa revisão considera:

  • design;
  • comportamento funcional;
  • clareza e complexidade;
  • testes;
  • nomes;
  • comentários;
  • aderência a convenções;
  • documentação associada.

Isso é importante porque muito problema real não aparece como “erro de compilação”. Problemas de acoplamento, clareza, manutenção e risco operacional também deveriam ser percebidos durante review.

Responsabilidade de quem abre a PR

Seção intitulada “Responsabilidade de quem abre a PR”

Quem autorou a mudança não é apenas responsável por escrever código. Também precisa facilitar a revisão.

Boas responsabilidades do autor:

  • manter a PR pequena e focada;
  • explicar motivação e contexto;
  • escolher reviewers com conhecimento relevante;
  • responder comentários com objetividade;
  • atualizar testes e documentação;
  • evitar deixar o reviewer adivinhando comportamento ou intenção.

Se a mudança for grande, vale planejar antes como quebrá-la em partes revisáveis.

Responsabilidade de quem revisa

Seção intitulada “Responsabilidade de quem revisa”

Revisar bem também é trabalho de engenharia, não favor informal.

Boas responsabilidades do revisor:

  • responder em tempo razoável;
  • priorizar pontos de maior impacto;
  • distinguir bloqueios reais de sugestões opcionais;
  • explicar o motivo do comentário;
  • evitar transformar gosto pessoal em regra universal;
  • registrar a decisão na própria PR.

Em times distribuídos e assíncronos, como mostra o handbook do GitLab, o review precisa deixar rastros claros no próprio merge request. Conversas em chat ajudam, mas não devem virar a única fonte da decisão.

Comentários bloqueantes e comentários opcionais

Seção intitulada “Comentários bloqueantes e comentários opcionais”

Um problema comum em review é misturar tudo no mesmo nível. Nem todo comentário deveria bloquear merge.

É útil distinguir:

  • comentário bloqueante: risco real, bug, violação de regra, falha de design importante, teste ausente, documentação obrigatória faltando;
  • comentário opcional: sugestão de melhoria, simplificação local, ideia futura, ajuste cosmético.

Essa distinção reduz ruído e evita que review vire disputa de estilo.

Ownership, governança e responsabilidade

Seção intitulada “Ownership, governança e responsabilidade”

Em times profissionais, colaboração madura não significa “qualquer um muda qualquer coisa sem contexto”. Geralmente existe alguma forma de ownership do código.

Isso pode aparecer em:

  • pessoas mantenedoras de um módulo;
  • áreas de domínio mais próximas de certas equipes;
  • CODEOWNERS;
  • aprovação obrigatória para áreas críticas;
  • branch protection e status checks.

Esses mecanismos não existem para burocratizar. Eles ajudam a reduzir risco e a direcionar revisão para quem tem mais contexto sobre determinado trecho do sistema.

CODEOWNERS e revisões direcionadas

Seção intitulada “CODEOWNERS e revisões direcionadas”

Arquivos como CODEOWNERS permitem que a plataforma solicite review automaticamente para pessoas ou equipes responsáveis por certas áreas.

Isso melhora:

  • rastreabilidade de responsabilidade;
  • velocidade de roteamento da revisão;
  • proteção de partes críticas do sistema;
  • consistência de decisão técnica.

Mas CODEOWNERS não resolve tudo sozinho. Se a cultura do time for ruim, ele vira apenas mais uma regra formal sem colaboração real.

Branch protection e status checks

Seção intitulada “Branch protection e status checks”

Muitos times internos usam proteções na branch principal para evitar integração direta sem validação.

Exemplos comuns:

  • exigir PR para merge;
  • exigir aprovação antes de mergear;
  • exigir status checks verdes;
  • bloquear merge em branch desatualizada com a base;
  • exigir aprovação de code owner em partes sensíveis.

Essas políticas tornam explícito que a branch principal é um ativo compartilhado do time, não uma área de experimento individual.

Decisões arquiteturais precisam de memória institucional

Seção intitulada “Decisões arquiteturais precisam de memória institucional”

Nem toda decisão relevante cabe em comentário de PR ou mensagem de commit. Quando a equipe faz escolhas arquiteturais importantes, essas decisões precisam de registro mais estável.

É aí que entram os ADRs, Architecture Decision Records.

O que é um ADR

Seção intitulada “O que é um ADR”

Um ADR registra uma decisão arquitetural significativa junto com seu contexto, alternativas e consequências.

Em termos simples, ele responde:

  • qual decisão foi tomada?
  • em que contexto?
  • que opções foram consideradas?
  • por que essa opção foi escolhida?
  • quais trade-offs e consequências ela traz?

Esse registro é valioso porque evita que o time precise rediscutir do zero, meses depois, algo que já foi analisado.

Quando abrir um ADR

Seção intitulada “Quando abrir um ADR”

Nem toda decisão merece ADR. Em geral, vale registrar quando a escolha:

  • afeta a estrutura do sistema;
  • impacta atributos de qualidade, como desempenho, segurança ou escalabilidade;
  • é difícil de reverter;
  • envolve trade-offs relevantes;
  • tende a reaparecer em discussões futuras.

Decisões pequenas e locais geralmente podem ficar em PR, issue ou documentação mais simples. ADR serve para decisões arquiteturalmente significativas.

Como escrever um ADR útil

Seção intitulada “Como escrever um ADR útil”

Fontes como a organização ADR e o Azure Well-Architected Framework convergem em alguns princípios.

Um ADR útil deve:

  • registrar uma decisão por vez;
  • manter formato consistente;
  • incluir contexto, opções, decisão e consequências;
  • deixar trade-offs explícitos;
  • usar status como Proposed, Accepted ou Superseded;
  • ser curto, assertivo e factual.

O ADR não deve virar ensaio teórico enorme. Seu valor está em tornar a decisão recuperável e auditável.

ADR é histórico, não texto reescrito continuamente

Seção intitulada “ADR é histórico, não texto reescrito continuamente”

Um princípio importante é tratar ADR como log histórico. Quando uma decisão muda, o ideal não é apagar a anterior como se ela nunca tivesse existido.

Em vez disso:

  • mantém-se o registro antigo;
  • cria-se um novo ADR com a nova decisão;
  • registra-se que o novo documento substitui o anterior.

Isso preserva a trilha de raciocínio do sistema ao longo do tempo.

README não é enfeite

Seção intitulada “README não é enfeite”

O README.md costuma ser o primeiro documento que alguém lê ao entrar no repositório. Em projetos saudáveis, ele funciona como porta de entrada.

Um README útil normalmente comunica:

  • o que o projeto faz;
  • por que ele existe;
  • como executar ou começar a usar;
  • onde encontrar documentação complementar;
  • como contribuir;
  • quem mantém ou onde pedir ajuda.

Sem isso, cada pessoa nova no time precisa descobrir o projeto por tentativa, conversa oral ou leitura difusa do código.

O README não deve virar enciclopédia

Seção intitulada “O README não deve virar enciclopédia”

Embora seja importante, o README não deve concentrar toda a documentação do projeto.

Quando ele cresce demais, costuma perder utilidade como porta de entrada. O melhor caminho é manter nele o essencial e apontar para documentos específicos quando o assunto exigir mais profundidade.

Exemplos do que pode ficar fora do README principal:

  • guia detalhado de contribuição;
  • histórico de versões;
  • políticas de segurança;
  • decisões arquiteturais;
  • runbooks operacionais;
  • documentação extensa de API.

Outros arquivos importantes do repositório

Seção intitulada “Outros arquivos importantes do repositório”

Projetos maduros costumam usar arquivos específicos para comunicar expectativas e reduzir ambiguidade.

Alguns exemplos:

  • CONTRIBUTING.md: como contribuir, abrir PR, reportar problema, seguir convenções;
  • CHANGELOG.md: mudanças relevantes para pessoas, não simples despejo de log de commits;
  • SECURITY.md: como reportar vulnerabilidades de forma responsável;
  • CODEOWNERS: responsáveis por áreas do código;
  • LICENSE: licença do projeto;
  • AUTHORS.md ou MAINTAINERS.md: autoria ou manutenção, quando isso fizer sentido no contexto do projeto.

Nem todo projeto precisa de todos esses arquivos, mas entender o propósito de cada um ajuda a desenhar um repositório mais comunicativo.

CHANGELOG é para humanos

Seção intitulada “CHANGELOG é para humanos”

Projetos que mantêm CHANGELOG.md bem cuidado ajudam pessoas usuárias, mantenedoras e outras equipes a entender o que realmente mudou entre versões.

Uma boa prática, defendida pelo Keep a Changelog, é tratar changelog como documento curado para humanos, e não como simples exportação de mensagens de commit.

Isso significa:

  • destacar mudanças relevantes;
  • agrupar por categoria;
  • indicar versão e data;
  • deixar claro o que foi adicionado, mudado, removido, corrigido ou depreciado.

CONTRIBUTING e templates ajudam a escalar colaboração

Seção intitulada “CONTRIBUTING e templates ajudam a escalar colaboração”

À medida que o time cresce, não dá para depender de instrução oral repetida para cada nova contribuição.

Arquivos como CONTRIBUTING.md e templates de issue/PR ajudam a padronizar entrada de informação. Eles podem orientar:

  • como abrir bugs úteis;
  • como propor mudanças;
  • que informações incluir em uma PR;
  • que checklist precisa ser cumprido;
  • que estilo ou fluxo o projeto espera.

Isso diminui ruído e melhora a qualidade média das interações.

Documentação boa é encontrável, viva e proporcional

Seção intitulada “Documentação boa é encontrável, viva e proporcional”

Não basta documentar; é preciso documentar bem.

Boas práticas para documentação interna incluem:

  • registrar processos recorrentes ou críticos;
  • escrever pensando em quem vai ler;
  • manter linguagem direta e escaneável;
  • centralizar a fonte principal de verdade;
  • revisar sempre que o processo mudar;
  • evitar documentação excessiva para eventos raros ou irrelevantes.

Documentação útil é aquela que alguém consegue encontrar, confiar e atualizar.

Comunicação assíncrona exige mais clareza

Seção intitulada “Comunicação assíncrona exige mais clareza”

Times distribuídos, híbridos ou muito ocupados dependem mais de comunicação assíncrona. Nesse cenário, clareza textual deixa de ser luxo e vira necessidade operacional.

Isso afeta diretamente:

  • descrições de PR;
  • comentários de review;
  • ADRs;
  • README e docs internas;
  • decisões registradas em issues ou tickets.

Se a decisão importante só aconteceu em uma call e nunca foi registrada, o time perdeu memória institucional.

Bônus: o que muda em open source

Seção intitulada “Bônus: o que muda em open source”

Embora este tópico tenha foco principal em times internos, vale observar algumas diferenças em projetos open source.

Em projetos abertos, costuma haver mais dependência de:

  • comunicação pública e assíncrona;
  • README, CONTRIBUTING.md e CODE_OF_CONDUCT mais completos;
  • fluxo baseado em fork e pull request;
  • paciência com tempo de resposta de mantenedores;
  • cuidado maior com contexto para pessoas externas ao projeto.

No open source, a documentação de entrada é ainda mais importante, porque muitas contribuições vêm de pessoas sem contexto institucional prévio.

Não transforme comunicação em burocracia vazia

Seção intitulada “Não transforme comunicação em burocracia vazia”

Existe um risco real de adotar todos esses artefatos de forma mecânica: PR template gigante, README inchado, ADR para qualquer detalhe e review usado para disputa de ego.

O objetivo não é produzir papelada. O objetivo é reduzir ambiguidade, melhorar entendimento e proteger a evolução do software.

Toda prática deve ser proporcional ao contexto do projeto e ao custo do erro.

Leituras e referências

Seção intitulada “Leituras e referências”