Definição curta

Distância entre o que um sistema faz e o que o time responsável por ele sabe explicar. Ela é contraída toda vez que um código é aceito sem que ninguém possa dizer por que ele foi escrito assim, e é paga em tempo gasto para reconstituir uma intenção que ninguém chegou a formar.

Definição detalhada

A expressão é decalcada da dívida técnica, de quem retoma a mecânica — uma vantagem imediata obtida contra um custo futuro majorado — mudando aquilo que é emprestado. A dívida técnica trata do estado do código; esta trata do estado da cabeça de quem o mantém.

Nos artigos deste blog, o termo designa a contrapartida do desenvolvimento assistido: um time que faz merge de código gerado, aceito e remendado sem que ninguém consiga explicá-lo obtém funcionalidade agora e incapacidade de diagnóstico depois. O passivo é invisível enquanto nada quebra, já que a aplicação roda, as telas respondem e os testes passam.

O sentido normativo gostaria de uma dívida mensurável e quitável por uma frente de trabalho identificada. O uso de campo não conhece nem contador nem prazo: ela é constatada no momento do incidente, quando um time descobre que não sabe mais por que tudo desaba, e sua quitação passa por uma releitura que ninguém mais tem tempo de fazer.

Uso no domínio

O termo entra em jogo nas regras de merge — recusar código que ninguém sabe explicar —, na arbitragem do orçamento de compreensão por funcionalidade (o contrato, os testes, a decisão de arquitetura, os limites conhecidos), e no diagnóstico de um time cujo ritmo de correção aumenta sem que o produto mude.

Sinônimos e variantes

"Código incompreendido", "aceitar código que não se explica". Expressões vizinhas usadas para o mesmo passivo: "um sistema que nunca foi habitado", "uma arquitetura cujas decisões ninguém tomou".

Não confundir com

• Dívida técnica — fragilidade de concepção que a empresa decidiu tratar, e que por isso carrega um custo e um lugar nas prioridades; ela é paga em trabalho de refatoração, enquanto a dívida de compreensão é paga em incapacidade de decidir o que refatorar — e ela espera uma decisão para existir, quando esta é contraída no merge.
• Reconstrutibilidade — propriedade de um sistema que um time saberia refazer em outro lugar; é o ativo do qual esta dívida é o passivo, e a pergunta "eu saberia reconstruir isso?" é a forma mais direta de constatar um ou outro.
• Dívida documental — ausência ou caducidade dos documentos que descrevem o sistema; um time pode ter documentado tudo e não entender nada, assim como pode entender tudo sem ter escrito nada.
• Bus factor — número de pessoas cuja saída tornaria um sistema inexplorável; ele mede a distribuição de uma compreensão que existe, não sua ausência.
• Legacy — sistema herdado cujas decisões foram tomadas em outro lugar e mais cedo; a dívida de compreensão se acumula sobre código escrito esta semana.

Exemplos

"Se um time aceita código incompreendido, ele aceita uma dívida de compreensão." — o uso de referência, colocado como consequência de uma regra de merge.

Dezenas de pull requests criadas durante a noite por um assistente e mescladas sem que ninguém tenha verificado os impactos: o volume entregue é passivo, não é adiantamento.

Uma aplicação que passa nos cenários felizes e contém centenas de escolhas técnicas geradas, aceitas, remendadas e depois esquecidas carrega a dívida inteira, mesmo que nenhum defeito tenha aparecido ainda.

Ambiguidades / debates

A palavra "dívida" sugere um montante e um prazo que nada aqui permite estabelecer: nenhuma prática atestada quantifica a distância entre o que um sistema faz e o que um time explica dele.

A atribuição continua em discussão: a dívida é carregada por quem fez o merge, ou pelo time que mantém? O uso adotado aqui a coloca sobre o time, já que é ele quem a paga.