Como documentar estruturas de código necessariamente complexas?

Se eu tenho um pedaço de código que é matematicamente ou estruturalmente bastante complexo e irredutível, como eu documentaria esse pedaço de código? Em particular, como posso garantir que alguém que não possua as habilidades matemáticas ou arquitetônicas que eu possuo possa entendê-lo na documentação? Também devo documentar toda a matemática? Link para um tutorial? Alguma ligação visual ajuda no caso de estruturas complexas?

Isso realmente depende de quão complicado é o código e a matemática. O próprio código deve - como sempre - ser o mais documentado possível. Nomear variáveis ​​corretamente, implementar métodos lógicos e concisos (em vez de mega-funções), adicionar documentação em linha onde apropriado (ou seja, quando não for óbvio o que o código está realmente fazendo).

Se você estiver usando um algoritmo não óbvio, adicione um link a uma referência à fonte. Essa é uma prática razoável, pois fornece ao desenvolvedor uma maneira muito rápida de descobrir o que você está fazendo. Como eu disse, isso é útil se for um algoritmo não óbvio, porém complexo. Isso deve provar que (a) você está fazendo algo que faz sentido; e (b) alguém demonstrou que funciona.

Um bom exemplo é um trabalho que fiz sobre a correspondência de texto difuso. Fiz uma pesquisa substancial sobre algoritmos e implementei o que é conhecido como 'algoritmo Smith-Waterman' (que é realmente usado para sequências de DNA, mas se aplica geralmente à 'correspondência'). Então, em vez de simplesmente implementar o algoritmo, encontrei referências on-line e incluí um link ou dois. Como acima, isso demonstra que (a) meu algoritmo corresponde ao algoritmo publicado e (b) o algoritmo foi revisado e mostrado para funcionar.

No entanto, isso não explica necessariamente como o código funciona e o que as várias classes devem fazer. Ao escrever uma documentação 'real' - um guia do desenvolvedor para o sistema - você deve explicar o que fez e fornecer informações suficientes para suporte futuro. Na minha opinião, este documento deve ser legível por uma pessoa tecnicamente agnóstica; não precisa ser "emburrecido", mas deve excluir o jargão e não confiar no conhecimento assumido.

Comentários em torno da fonte são a primeira coisa que você deve fazer. Isso garante que haja um link direto para a documentação diretamente pelo código. Se a documentação for muito complicada, considere postar apenas um resumo nos comentários e, em seguida, um link para algum documento externo que contenha uma descrição mais completa da arquitetura / algoritmo complexo. Se não for muito complicado, considere incluir toda a documentação em um só lugar. Isso maximizará a probabilidade de seu código / documentação permanecer sincronizado e serem lidos juntos.

Documente o código na medida em que sua equipe / empresa precisar. Se um jr. O dev será necessário para manter o código, talvez você precise entrar em detalhes sobre algumas das contas. Esta é uma decisão de gerenciamento e eles precisam fornecer o tempo necessário.

Não acho que você precise documentar tanto o código que considere ter sido substituído por um desenvolvedor menor. Se isso é uma preocupação, você precisa ter tempo para documentar.

Você não deveria ter que fazer a pesquisa na web para eles.