Quais são as boas maneiras de documentar software científico?

Muitas vezes, quando eu herdei ou encontrei código científico escrito por outras pessoas (ou ocasionalmente, até meu próprio trabalho), notei que a documentação é esparsa ou inexistente. Se tiver sorte, vejo comentários informativos. Se eu tiver muita sorte, há até comentários Doxygen e um Doxyfile para que eu tenha interfaces de função e algum HTML formatado para consultar. Se eu tiver muita sorte, há um manual em PDF e exemplos, além dos comentários sobre o Doxygen e os arquivos de origem, e estou em êxtase, porque torna minha vida muito, muito mais fácil.

Quais informações e ferramentas são úteis para documentar o código-fonte? Nesse caso, que informações e ferramentas são úteis para documentar os dados e resultados que acompanham esse código-fonte, no caso de software científico?

Penso que a documentação para software científico pode ser dividida em três categorias, todas necessárias para um entendimento completo. O mais fácil e mais comum é a documentação de métodos individuais. Existem muitos sistemas para isso. Você mencionou doxygen , o Python possui o pydoc e, no PETSc, temos nossa própria semeadura de pacotes, que gera o seguinte .

No entanto, para qualquer software que vá além de um utilitário simples, você precisa de um manual. Isso fornece uma visão de alto nível do objetivo do pacote e como suas diferentes funcionalidades se integram para atingir esse objetivo. Ajuda um novo usuário a estruturar seu código, geralmente através do uso de exemplos. No PETSc, usamos apenas o LaTeX para o manual, mas o pacote PyClaw usa a estrutura Sphinx com a qual estou muito impressionado. Uma coisa que implementamos no pacote de semeadura que considero muito útil é o link entre o código de exemplo e a documentação da função. Por exemplo, este exemploresolve a equação de Bratu. Observe como você pode seguir os links para qualquer tipo personalizado ou chamada de função e acessar a documentação de baixo nível, e como essas páginas são vinculadas a exemplos de uso. É assim que eu aprendo sobre as novas funcionalidades com as quais outras pessoas no projeto contribuem.

Uma parte frequentemente esquecida da documentação, eu acho, é a documentação do desenvolvedor. Não é incomum publicar um documento no estilo de codificação e instruções para interagir com o repositório. No entanto, é muito raro explicar as decisões de design tomadas antes da implementação. Essas decisões sempre envolvem tradeoffs, e a situação em relação ao hardware e algoritmos necessariamente muda com o tempo. Sem uma discussão sobre as compensações revisadas e a justificativa para decisões de design específicas, os programadores posteriores são deixados a recriar todo o processo por conta própria. Eu acho que esse é um grande impedimento para a manutenção e aprimoramento bem-sucedidos de códigos antigos quando os desenvolvedores originais não estão mais no comando.

Documentação no código

O mais importante é usar os recursos de documentação no ambiente de desenvolvimento escolhido, o que significa pydoc para python, javadoc em java ou comentários xml em C #. Isso facilita a gravação 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 concentra-se 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 sobre o nível do sistema e a documentação arquitetural. Muitos defenderiam 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 é o código, em um formato de texto sem formatação que seja amigável ao sistema de controle de versão.

Assim como na documentação em código, se você armazena sua documentação de nível superior em seu repositório de código, é 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ê usar um formato compatível com VCS, significa que é fácil ramificar, diferenciar e mesclar sua documentação, assim como seu código.

Eu gosto bastante de reStructuredText (rst) , pois é fácil produzir páginas html e documentos PDF usando esfinge e é muito mais amigável que o LaTeX , mas ainda pode incluir expressões matemáticas do LaTeX quando você precisar delas.

Farei objeção a quase todos os argumentos que Faheem faz . Especificamente:

1 / "Penso que não é realista esperar que desenvolvedores científicos gastem muito tempo documentando seu software". Essa é uma receita para um projeto com falha que em breve ninguém poderá usar quem não tem acesso aos desenvolvedores principais. É por uma boa razão que as grandes bibliotecas de computação científica (por exemplo, PETSc ou deal.II) possuem uma extensa documentação que chega a milhares de páginas ou mais. Você não pode ter uma comunidade de usuários considerável se não tiver uma documentação extensa. Concordo, no entanto, que exemplos de códigos precisam ser simples e focados em um único conceito.

2 / "os autores devem considerar escrever um artigo para publicação, se apropriado". Isso geralmente não é possível na prática. Pode-se escrever trabalhos sobre conceitos e algoritmos, mas não sobre interface e outras decisões de design. Os leitores desses documentos terão uma idéia do que a implementação faz; os usuários da implementação precisarão saber quais funções chamar, o que os argumentos significam etc. Como usuário, na maioria das vezes, é possível viver sem o primeiro e simplesmente considerar uma biblioteca como uma caixa preta, mas não se pode prescindir disso. informações de interface.

Essa é uma boa pergunta. Para uma primeira aproximação, o código deve tentar ser auto-documentado. Assim, por exemplo, se o software é linha de comando, você deve ser capaz de fazer executable --helpou executable -hou mesmo executable(se o executável não faz nada sem argumentos), e tem uma mensagem de retorno de uso breve.

Segundo, acho que não é realista esperar que desenvolvedores científicos gastem muito tempo documentando seu software, então sugiro que seja simples. Um pequeno manual de texto com os métodos e opções básicos e anotado trabalhando e testadoexemplos de uso, graduados de simples a mais complexos (os exemplos de uso são muito importantes e freqüentemente negligenciados) é consideravelmente melhor que nada e muito mais do que a maioria das ofertas científicas de software. Eu também gostaria de adicionar uma opinião sobre exemplos de uso. Simples significa simples. Isso significa que, se você está tentando ilustrar um método, não adiciona dez conceitos ou métodos estranhos para confundir o leitor. Mantenha-o simples e faça anotações para que o leitor saiba o que o exemplo deve estar fazendo. Eu também sugeriria amarrar os exemplos de uso manual em um conjunto de testes de alguma forma, para que eles continuem trabalhando quando o código for alterado. Na verdade, eu não sei como fazer isso de uma maneira agradável; portanto, fique à vontade para me educar. Se os desenvolvedores quiserem ser mais sofisticados, certifique-se de que possam usar boas linguagens de marcação e assim por diante, adicione páginas de manual e assim por diante.

Terceiro, os autores devem considerar escrever um artigo para publicação, se apropriado. Isso geralmente abordaria as decisões de design e forneceria uma perspectiva de mais alto nível sobre o software do que um manual, ou pode-se esperar. Isso abordaria a documentação das decisões de design sobre as quais o @Matt estava falando.

Obviamente, a documentação mais importante de todas é o próprio código, que deve ser comentado conforme necessário. Isso pressupõe que o código é um software livre. Caso contrário, é substancialmente menos útil como software científico (você realmente deseja usar uma caixa preta onde não consegue ver como os métodos são implementados?) E eu, pelo menos, não o usaria.

Para responder à sua pergunta sobre como documentar dados e resultados, recomendo algo como o módulo doctest do Python . Isso permite que você escreva tutoriais ou testes de uma maneira que possa ser validada automaticamente.

Se você está interessado em programação alfabética, dê uma olhada no org-babel . Faz parte do modo organizacional no Emacs e, portanto, oferece uma ampla variedade de opções de exportação (LaTeX, PDF, HTML, ODT) para documentação. O Emacs pode exibir imagens dentro do buffer e permitir que você escreva equações matemáticas na sintaxe do LaTeX, para que você não precise se limitar à documentação em texto simples.

A documentação que é derivada automaticamente do seu código-fonte é um componente essencial para se manter atualizado, ou seja, a documentação correta. Não sei contar quantas vezes vi a documentação anos atrás do código-fonte devido à apatia do desenvolvedor em relação à documentação. A solução fácil é facilitar para os programadores escreverem a documentação juntamente com o novo código no mesmo local e ao mesmo tempo, e não como um esforço posterior que será inevitavelmente desprotegido em favor de atividades mais gloriosas.

Se forçado a escolher, prefiro ter comentários detalhados e precisos sobre o código-fonte (atual), mas nenhum manual do usuário que um manual desatualizado e cheio de informações erradas.

No Python, existem as ferramentas pep8 e pep257 que relatam documentação ausente ou malformada. O elpy para o Emacs também reclamará da falta de documentação. É conveniente seguir as convenções de documentação do Numpy com reStructuredText. O teste com pep8, pep257 e doctest pode ser configurado com o py.test e o tox executando automaticamente.