18-always-honest

"Sempre honesto, nunca assumir." É uma regra que escrevi no topo do guia de contributors do meu SDK. A origem é um erro pequeno que me ensinou uma coisa para a qual eu não tinha palavras.

Na primavera passada estava a escrever docs para o vendus-python — SDK Python para a maior plataforma de faturação portuguesa. Uma página dizia:

"O Vendus não tem sandbox público."

Confiante. Declarativo. Errado de uma forma específica: o maintainer upstream e eu não tínhamos confirmado isso. O CLAUDE.md do repo (o ficheiro que guia o meu par AI) ainda listava sandbox como TBD — investigar. Os docs e a memória de trabalho do projecto contradiziam-se, e os docs soavam mais seguros.

Essa contradição é exactamente o bug. Uma frase confiante sem fonte é mais difícil de corrigir mais tarde do que um TBD humilde, porque ninguém sabe por onde começar.

Por isso a regra:

→ No código: afirmações sobre APIs externas têm de citar a fonte (página de docs do Vendus, resposta de erro que vimos, email de suporte). Sem fonte → é comentário TBD, não código silencioso.
→ Nos docs: claims sobre comportamento do gateway têm de estar verified-in-this-PR ou marcadas como assumed. Nada de generalizações silenciosas.
→ Nas respostas (a issues, PRs, utilizadores): "ainda não sei, deixa-me confirmar" bate "acho que está bem".

O custo da regra é pequeno — uns TBDs a mais por trimestre. O benefício é que os docs e o código nunca derivam, e ninguém entrega uma mentira de aspecto confiante.

Qual é a frase mais honesta nos docs do teu projecto?

Repo: github.com/bilouro/vendus-python

P.S. Novo post tech toda a quarta-feira aqui no LinkedIn.

#OpenSource #Python #SoftwareArchitecture