Metodologia para documentar a base de código existente

Trabalho como parte de uma equipe em um aplicativo existente que não possui documentação em linha nem documentação técnica. Enquanto eu trabalhava em vários relatórios de bugs no aplicativo, escrevi uma espécie de trilha de trilha para mim - números de bugs em vários lugares para que o próximo desenvolvedor possa se referir a esse número de bugs para ver o que estava acontecendo.

Minha pergunta é assim:

Qual é o método mais eficiente para documentar esse código? Devo documentar enquanto toco na área (o método do vírus, se preferir) ou devo documentar sozinho cada seção e não seguir caminhos que se ramificam em outras áreas do aplicativo? Devo inserir comentários embutidos onde não existiam anteriormente (com medo de que eu possa acabar identificando incorretamente o que o código faz)?

Que método você usaria para documentar com precisão e rapidez um aplicativo bastante grande que não possui documentação embutida existente nem referências embutidas à documentação externa?

Documentando bases de código herdadas

Eu recomendo seguir a regra dos escoteiros com bases de código herdadas. Tentar documentar um projeto legado independentemente de trabalhar nele nunca acontecerá.

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 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 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 também é 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ê armazenar 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, 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.

Questão capciosa. Basicamente, eu usaria o método "refatoração", que eu reformularia como "se você tocar no código, documente-o".

Mas para ser preciso; à medida que surgem problemas e como você precisa se familiarizar com o código para corrigir os erros que ocorrem, eu diria que você deve usar essa familiaridade para escrever comentários sobre esse código em particular; em essência, a motivação para corrigir o bug naquele momento forçou você a familiarizar-se o suficiente com o código para poder documentá-lo. E, por esse motivo, eu desconfio de seguir ramificações não relacionadas OU de documentar funções não relacionadas, porque nesse momento, se você não estiver executando testes ativos do código (para verificar sua correção de bug), é difícil ser totalmente certo de que você entende exatamente o que o código faz e por quê. (Não estou entrando no problema de que também pode ser difícil descobrir com precisão o que e por que o código faz o que faz, mesmo ao testar uma correção de bug; você '

Essa abordagem deve tender a maximizar a precisão, com um sacrifício da velocidade geral, mas não afeta sua necessidade de manter o código muito severamente ao mesmo tempo. Se suas tarefas de correção de bugs são pequenas, é claro, você pode se aventurar em "território desconhecido" e começar a documentar lá, mas se você (como a maioria de nós) não encontrar tempo suficiente no dia para corrigir o código e documentá-lo, isso é um bom compromisso.

Uma coisa vale a pena notar também; você deve ter boa documentação externa. Você diz que seu código não tem referências a documentação externa; Espero por você que essa documentação externa exista. Caso contrário, eu faria da escrita dessa documentação externa sua primeira prioridade; acho que algo no nível de uma especificação funcional é absolutamente crítico para todos os grandes projetos de software. O motivo é que as especificações funcionais, ou a documentação de alto nível desse formulário, podem ajudar a impedir a "fluência de recursos" ou "desvio de recursos" em qualquer software; e o desvio de recurso (em particular) pode ser destrutivo para a documentação, pois pode tornar a documentação desatualizada. (Defino a fluência de recursos como a adição progressiva (e irritante) de recursos a um software; desvio de recurso, por outro lado, é onde o conjunto de ações que o software executa lentamente muda ao longo do tempo. A fluência de recursos é ADITIVA, ou seja, geralmente envolve o aumento do conjunto de funcionalidades do software; a deriva do recurso, por outro lado, é de soma zero; um por um, uma parte da funcionalidade de borda é definida para fazer algo diferente, até que o software esteja fazendo algo completamente diferente do que o originalmente pretendido. O desvio de recursos é raro, mas MORTALMENTE para documentação.)

Um aplicativo que eu co-desenvolvi ao longo de dois anos teve uma séria falta de documentação. Em algum momento, ficou claro que passaríamos o aplicativo para outro desenvolvedor que o manteria daquele ponto em diante, portanto, tivemos que documentar o código.

Para lidar com o escopo gigantesco do processo de documentação, eu tentaria documentar todo o código em um recurso específico ou parte do aplicativo em um determinado dia. Eu não tinha um padrão específico, mas insistia em fazer alguns a cada dia e em obter uma sensação de conclusão documentando diariamente um arquivo ou seção inteira do aplicativo.

Demorou meses para documentar o aplicativo inteiro, mas a meia hora (no máximo) por dia ele nunca entrou no cronograma do projeto e evitou muito tédio que acompanha a documentação.

Usamos a documentação XML em C # e fornecia recursos e estruturas suficientes para facilitar a documentação. Mesmo que você não esteja documentando um aplicativo C #, o padrão de ter um breve resumo primeiro seguido de comentários foi muito útil.

Eu documentaria como adicionei / modifiquei o código. Fora isso, eu também documentaria APIs públicas ou quaisquer interfaces entre módulos. Se você documentar todo o código, talvez não veja o ROI do tempo gasto. Pode ser útil usar algo como um wiki para organizar a documentação externa à medida que você a desenvolve. O documento mais útil que referenciei quando iniciei meu último projeto foi o documento de arquitetura. Ele incluía informações sobre as tecnologias usadas e fornecia uma visão de alto nível de como o aplicativo foi colocado em camadas.

Eu usaria comentários do Doxygen. O Doxygen possui mais formatos de saída que a maioria dos outros formatos gratuitos e é simples de aprender.

Você pode até considerar contratar um empreiteiro para fazer isso, como alguns de nós fazem para viver. No entanto, com essa opção, você ainda precisa se comprometer em revisar os documentos.

Outra técnica comum é atribuir o novo desenvolvedor à documentação do código. Em seguida, faça com que cada nova pessoa passe por ela à medida que se atualizar. Esteja ciente de que alguns desenvolvedores consideram isso como um canal radicular - necessário apenas nos casos diretos, LOL.

Antes de começar a documentar qualquer coisa, desenvolva um padrão. Isso pode ser tão simples quanto garantir que você escreva algumas linhas acima de uma função ou cabeçalho de classe para algo mais oficial e detalhado (como javadoc). Antes que alguém possa verificar o código, sua documentação deve atender a esse padrão.

O que eu descobri que funciona bem é adicionar comentários bem escritos antes do cabeçalho da função às funções que eu criei anteriormente não documentadas e adicionar comentários embutidos a qualquer coisa que eu tenha adicionado. Você deseja evitar documentar o código que não tocou. É pior ter comentários ruins do que nenhum comentário, e se você estiver documentando isso 'rapidamente', provavelmente escreverá comentários ruins.