4 posts
A programação literária mantém a documentação, os testes e a implementação sincronizados ao tornar um ficheiro Markdown a única fonte de verdade. Eis como implementá-la em trinta linhas de Python.
A sua documentação, testes e código são três ficheiros a contar a mesma história mal. Atualiza a assinatura da função no source. Esqueces o exemplo do README.…
Conversas com LLM contêm intenção, alternativas rejeitadas e código funcional. É exatamente isso que a documentação deveria ser. Veja como transformar um chat efêmero em documentos duráveis e pesquisáveis sem perder a narrativa.
Você passou quarenta e cinco minutos com Claude projetando um circuito de retry. Você explicou os modos de falha, rejeitou o backoff exponencial porque esconde…
A programação literária prometia que o código deveria ser escrito primeiro para humanos e depois para máquinas. Quatro décadas depois, quase ninguém escreve assim. Veja por que a ideia mais elegante da documentação de software não conseguiu mudar a forma como trabalhamos.
Em 1984, Donald Knuth publicou um artigo que propunha uma inversão radical. Programas não deveriam ser escritos para compilers e anotados para humanos.…
A documentação de arquitetura apodrece no momento em que a guardas. Eis como manter os docs honestos usando diagramas gerados a partir de código, ADRs e testes de arquitetura automatizados.
Cada diagrama de arquitetura que vi numa wiki estava errado. Não dramaticamente errado. Apenas silenciosamente, incrementalmente errado. O serviço etiquetado…