Onde um programador deve explicar a lógica estendida por trás do código?

Eu desenvolvi algumas bibliotecas quantitativas em C # onde é importante entender não apenas as informações clássicas que acompanham os comentários XMLDoc (que contêm informações básicas com a assinatura do método), mas também as fórmulas matemáticas usadas nos métodos.

Por isso, gostaria de poder incluir documentação estendida com o código, que poderia conter, por exemplo, fórmulas de látex, gráficos e assim por diante.

Você acha que essas informações devem ser incluídas na documentação da API?

Ou deveria ser incluído em um blog de desenvolvimento para obter exemplos?

Existem ferramentas comuns que geralmente são usadas para esse tipo de finalidade?

No que me diz respeito, quanto mais você mantém a documentação do código, maior a probabilidade de ela ser mantida atualizada e mais útil é provável.

É por isso que tento manter toda a documentação no mesmo repositório que o código, mesmo os manuais do usuário, e tento mantê-la em um formato de texto sem formatação que pode ser facilmente gerenciado por um sistema de controle de revisão.

Documentação no código

Parece que você já tem este assunto coberto, mas é importante lembrar que, na verdade, o uso dos recursos de documentação no ambiente de desenvolvimento escolhido ( pydoc para python, javadoc em java ou comentários xml em C #) é a técnica de documentação mais importante. Eles facilitam a escrita da documentação ao mesmo tempo que o código.

Se você confiar em voltar e documentar as coisas posteriormente, talvez não consiga contornar isso, mas se fizer isso ao escrever o código, o que precisa ser documentado ficará em sua mente. O C # ainda tem a opção de emitir um aviso de compilação se a documentação XML estiver incompleta ou inconsistente com o código real.

Testes como documentação

Outro aspecto importante é ter uma boa integração e testes de unidade.

Frequentemente, a documentação se concentra no que classes e métodos fazem isoladamente, ignorando como eles são usados ​​juntos para resolver seu problema. Os testes geralmente os colocam em contexto, mostrando como eles interagem entre si.

Da mesma forma, testes de unidade frequentemente apontam explicitamente dependências externas através das quais as coisas precisam ser zombadas .

Também acho que, usando o desenvolvimento orientado a testes, escrevo um software que é mais fácil de usar, porque estou usando desde o início. Com uma boa estrutura de teste, tornar o código mais fácil de testar e fácil de usar geralmente é a mesma coisa.

Documentação de nível superior

Finalmente, há o que fazer em relação ao nível do sistema, arquitetura, desenvolvedor e possivelmente também documentação do usuário final. Muitos advogariam escrever essa documentação em um wiki ou usar o Word ou outro processador de texto, mas para mim o melhor lugar para essa documentação também é o código, em um formato de texto sem formatação, que é amigável ao sistema de controle de versão.

Assim como na documentação no código, se você armazenar sua documentação de nível superior no seu repositório de códigos, é mais provável que a mantenha atualizada. Você também obtém o benefício de que, ao extrair a versão XY do código, também obtém a versão XY da documentação. Além disso, se você usa um formato compatível com VCS, significa que é fácil ramificar, diferenciar e mesclar, assim como seu código.

Eu gosto bastante do primeiro , pois é fácil produzir páginas html e documentos PDF a partir dele, e é muito mais amigável que o LaTeX , mas ainda pode incluir expressões matemáticas do LaTeX quando você precisar.

Ao escrever código altamente matemático, também acho útil ter alguns documentos wxmaxima no meu repositório de projetos. Sendo texto simples, eles também ramificam, diferenciam e mesclam-se muito bem, mas o uso de um sistema de álgebra computacional pode ajudá-lo a verificar consistentemente suas fórmulas e a documentá-las.

Você pode incluir essa documentação nos comentários XML e gerar manuais, páginas da Web e outros documentos do LaTeX usando o doxygen . Use os elementos <remarks>e <example>para a prosa estendida.

Eu usaria documentação externa se você precisar incluir diagramas de classes, gráficos, fórmulas, imagens etc. para explicar como suas bibliotecas funcionam. Inclua essa documentação externa como parte dos lançamentos da sua biblioteca, em qualquer formato que você considere apropriado (LaTeX ou não). Você pode consultar este documento a partir do seu código, se desejar (por exemplo, "consulte a documentação" Leia-me "para obter mais informações.").

A chave, acredito, é a consistência . Se você anotou de forma consistente os métodos com comentários que podem ser extraídos, por exemplo, com o Doxygen, faz sentido incluir também a descrição lógica estendida, pois é nesse ponto que os desenvolvedores provavelmente procurarão. De repente, apontar o desenvolvedor para outro documento parece desnecessário e apenas confundirá os desenvolvedores.

No entanto, se a descrição de todo o programa for fornecida em outro lugar, você deve continuar com isso e fornecer a descrição lógica estendida.

Se você acha que é necessário documentar as entranhas de um método em sua API, provavelmente não definiu / modularizou a interface muito bem.

Uma API bem escrita não deve exigir que o programador entenda como os internos funcionam. Além disso, ao documentar desnecessariamente o funcionamento, você está quebrando a camada de abstração e bloqueando-se em uma implementação específica, o que também não é bom.