Piousbox

tl;dr: código de produção, código de ensaio e documentação.

Contadores públicos certificados são usados para escrever coisas duas vezes, no sistema de contabilidade de dupla entrada. Isto ajuda a evitar alguns erros. Programadores em línguas interpretadas, como eu, são usados para testar o desenvolvimento (TDD), onde cada peça de funcionalidade é razoavelmente coberta por um teste. De uma forma que é um sistema de dupla entrada. No entanto, falta pelo menos uma peça.

Descobri que se eu não documentar a funcionalidade, é como se ela desaparecesse, ou nunca estivesse lá. Então eu fiz uma regra para escrever alguma documentação para cada bit exposto - seja ele um pedaço de funcionalidade, ou um elemento de uma UI. No mínimo, estou anotando o trabalho feito no changelog/worklog. E vou tornar isso público. Publicar ou perecer, certo, e se uma funcionalidade é implementada por nunca usado, ninguém é melhor para ele.

Descrever a interface de usuário em um arquivo README.txt é realmente bom o suficiente. Sei porque estou sempre a lê-las. Preencher a pasta doc/ no repo também se mostrou útil. Se não me lembro de como alguma coisa foi feita, talvez possa lê-la lá. E se eu escrever documentação que nunca será lida - hey, isso também está bem.

Muitas vezes a documentação está faltando ou é sub-par. Ao mesmo tempo, muitos recursos online descrevem coisas que não existem, ou são lixo. Porque não reconciliamos os dois? Programe ferramentas úteis, *e* escreva a documentação sobre como usá-las.

Bom software merece boa documentação. A grande engenharia não é só sobre escrever código. Trata-se também de compartilhar seus conhecimentos e tornar seus conhecimentos úteis.