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

44

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?

Geoff Oxberry
fonte
3
Em R, pode-se usar roxygen (2) e / ou Sweave para documentar código e escrever vinhetas (manuais).
Roman Luštrik
2
Um excelente exemplo são os tutoriais do deal.ii que não apenas ensinam como usar o software, mas também como elementos finitos funcionam.
David Ketcheson
Me recomendaram o M2HTML para facilitar a documentação do código matlab.
Artem Kaznatcheev
org-mode é brilhante programação alfabetizada multi-lingual
David LeBauer

Respostas:

45

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.

Matt Knepley
fonte
+1 para a Esfinge! Observe que ele inclui autodoc , que eu acho muito superior ao pydoc.
David Ketcheson
3
+1 para a separação na documentação da interface / usuário / desenvolvedor.
Florian Brucker
19

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.

Mark Booth
fonte
Gostaria de apontar para Lyx( lyx.org ) para escrever LaTeXdocumentos para documentação de suporte de código.
Ja28
Eu usei o Lyx no passado, mas o que mais gosto rsté que posso escrevê-lo em um editor de texto normal (no mesmo IDE que uso para escrever código) e ainda assim ter certeza de que sei qual será o documento final gostar. Além disso, as convenções de formatação o tornam muito amigável para VCS, o que é algo importante para mim.
Mark Booth
15

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.

Wolfgang Bangerth
fonte
1
Bem-vindo, Wolfgang; Acho que você é a pessoa certa para responder a essa pergunta, mas tenho uma sugestão: o que você escreveu aqui talvez deva ser um comentário à resposta de Faheem, em vez de uma resposta à própria pergunta.
David Ketcheson
Eu vejo agora, de fato. Eu acho que não tinha percebido na época como isso funciona.
Wolfgang Bangerth
@WolfgangBangerth: Obrigado por seus comentários, que eu não vi porque não fui notificado. Eu acho que talvez um @ na frente do Faheem tivesse feito isso, mas eu não tenho uma boa referência. Tentarei abordar seus comentários na minha resposta - não há espaço suficiente em um comentário.
Faheem Mitha
@FaheemMitha: Você escreveu a resposta? O problema com novas respostas para uma pergunta é que eles são re-ordenada com base em quantos Up- / downvotes eles ficam enquanto comentários permanecer linear ...
Wolfgang Bangerth
@WolfgangBangerth - É precisamente por esse motivo que é uma boa prática referenciar adequadamente uma resposta e mencioná-la. É muito rápido e simples de fazer, basta ir para a resposta, clicar no link, copiar o link curto, escolher sua resposta, selecionar o texto que você deseja transformar em um link (como eu fiz para o seu), clicar no Hyperlink botão e cole no link. Qualquer um pode rapidamente acessar a resposta que você está referenciando, independentemente de ter sido votada mais ou menos que a sua própria resposta.
Mark Booth
9

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.

Faheem Mitha
fonte
5

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.

Juan M. Bello-Rivas
fonte
5

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.

wdkrnls
fonte
1
Um recurso relevante do modo organizacional é que ele executa c, SQL, bash, R, python e muitas outras linguagens, perfeitamente no texto.
David LeBauer
1

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.

Jeff
fonte
0

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.

Finn Årup Nielsen
fonte