O código como material

Há uma diferença entre usar uma ferramenta e trabalhar um material. A ferramenta se escolhe pela função; o material se conhece pelo comportamento. Quem serra madeira sabe que a peça responde ao corte, e que a resposta muda a próxima decisão.

Software costuma ser tratado como a primeira coisa. Escolhe-se uma linguagem, uma biblioteca, um editor, e segue-se para o problema de verdade. Mas há um ponto do trabalho em que o código deixa de ser instrumento e passa a participar da forma final — e a partir dali ele se comporta muito mais como material do que como ferramenta.

O momento da virada

A virada não acontece na primeira linha. Acontece quando uma decisão técnica passa a ser legível de fora: quando a escolha de guardar uma data como texto, e não como instante, muda o que o documento pode afirmar sobre si mesmo.

Um contrato assinado não é um texto com uma imagem no rodapé. É uma afirmação sobre um instante.

C. Ventura, O que um documento guarda

É por isso que decisões que parecem de implementação — usar created_at ou congelar um snapshot, por exemplo — acabam sendo decisões de produto. O material não separa as duas coisas.

Três sinais de que virou material

1. A escolha técnica muda o que se pode prometer a quem usa.
2. Desfazê-la exige explicar a decisão, e não só reescrever o trecho.
3. Alguém de fora consegue perceber a consequência sem ler o código.

A imagem acima extravasa a coluna de propósito. Nem toda figura precisa disso — um diagrama pequeno lido junto com a frase deve ficar na largura do texto, porque ele é parte da frase.

Escrever para quem vai mexer depois

Material tem grão, e o grão de um sistema é a razão pela qual cada coisa está onde está. Um comentário que explica o quê envelhece com o código; um que explica por quê sobrevive à reescrita.

// Não é curinga de propósito: um `/:slug` genérico capturaria
// o 404 do servidor e renderizaria algo por cima dele.
if (pathname === CAMINHO_DE_EXPLORAR) return ROTA_DE_EXPLORAR;

O trecho acima não é bonito nem esperto. Ele diz uma coisa que ninguém adivinharia sozinho, e é isso que o torna útil seis meses depois. Mais sobre essa distinção em Medir antes de consertar.

Talvez seja essa a única definição de ofício que resiste: saber o que o material faz quando ninguém está olhando, e escrever de forma que a próxima pessoa também saiba.