Como fazer documentação para código e por que o software (geralmente) é mal documentado?

Existem alguns bons exemplos de códigos bem documentados, como o java api. Porém, muitos códigos em projetos públicos, como o git e os projetos internos das empresas, são mal documentados e pouco amigáveis ​​para os iniciantes.

Em todas as minhas etapas de desenvolvimento de software, tive que lidar com códigos mal documentados. Notei as seguintes coisas -

1. Pouco ou nenhum comentário no código.
2. Os nomes de métodos e variáveis ​​não são auto-descritivos.
3. Há pouca ou nenhuma documentação sobre como o código se encaixa no sistema ou nos processos de negócios.
4. Contratar desenvolvedores ruins ou não orientar os bons. Eles não podem escrever código simples e limpo. Portanto, é difícil ou impossível para qualquer pessoa, incluindo o desenvolvedor, documentar o código.

Como resultado, tive que passar por muito código e conversar com muitas pessoas para aprender coisas. Eu sinto que isso desperdiça o tempo de todos. Também cria a necessidade de sessões de transferência de conhecimento / conhecimento para iniciantes em um projeto.

Aprendi que a documentação não recebe a atenção que merece devido aos seguintes motivos:

1. Preguiça.
2. Os desenvolvedores não gostam de fazer nada além de código.
3. Seguro desemprego. (Se ninguém puder entender seu código facilmente, talvez você não seja facilmente substituível.)
4. Prazos difíceis deixam pouco tempo para documentar.

Então, estou me perguntando se existe uma maneira de incentivar e impor boas práticas de documentação em uma empresa ou projeto. Quais são as estratégias a serem usadas para criar documentação decente para os sistemas e o código de qualquer projeto, independentemente de sua complexidade? Existem bons exemplos de quando é necessária uma documentação mínima ou nenhuma?

IMHO, sinto que deveríamos ter uma revisão da documentação após a entrega de um projeto. Se não for simples, conciso, ilustrativo e fácil de usar, o desenvolvedor ou o engenheiro de documentação técnica é o responsável por isso e deve corrigi-lo. Não espero que as pessoas façam resmas de documentação, não espero que seja fácil de usar como nos primeiros livros, mas espero que elimine a necessidade de horas de análise e sessões de KT desperdiçadas.

Existe uma maneira de acabar ou aliviar essa loucura? "Desenvolvimento orientado a documentos", talvez?

Como documentar código?

Você já tem uma dica: veja como a API Java está documentada.

De maneira mais geral, não há um conjunto exclusivo de regras que se aplique a todos os projetos. Quando trabalho em projetos de grande escala críticos para os negócios, a documentação não tem nada a ver com a que eu escreveria para uma pequena biblioteca de código aberto, que, por sua vez, não tem nada a ver com a documentação do meu projeto pessoal de média escala .

Por que muitos projetos de código aberto não estão bem documentados?

Porque a maioria dos projetos de código aberto é feita por pessoas que contribuem para esses projetos porque é divertido. Muitos programadores e desenvolvedores consideram que escrever documentação não é divertido o suficiente para ser feito de graça.

Por que muitos projetos de código fechado não estão bem documentados?

Porque custa uma quantia enorme de dinheiro para (1) escrever uma boa documentação e (2) mantê-la.

1. O custo imediato (custo de redação da documentação) é claramente visível para as partes interessadas: se sua equipe pedir para passar os próximos dois meses documentando o projeto, serão necessários dois meses adicionais de salário.

2. O custo de longo prazo (custo de manutenção da documentação) também se torna muito fácil de ser percebido pelos gerentes, e geralmente é o primeiro alvo quando eles devem reduzir o custo ou reduzir os atrasos. Isso causa um problema adicional de documentação desatualizada que rapidamente se torna inútil e é extremamente caro para atualizar.

3. As economias de longo prazo (economia por não ter que perder alguns dias explorando o código legado apenas para entender algo básico que deveria ter sido documentado anos atrás) são, por outro lado, difíceis de medir, o que confirma o sentimento de alguns gerentes que escrever e manter a documentação é uma perda de tempo.

O que eu frequentemente observo é que:

1. No início, a equipe está disposta a documentar muito.

2. Com o tempo, a pressão dos prazos e a falta de interesse tornam cada vez mais difícil manter a documentação.

3. Alguns meses depois, uma nova pessoa que ingressa no projeto praticamente não pode usar a documentação, porque ela não corresponde ao sistema real.

4. Percebendo isso, a gerência culpa os desenvolvedores por não manterem a documentação; os desenvolvedores pedem para passar algumas semanas atualizando-o.

   • Se a gerência conceder algumas semanas para isso, o ciclo se repetirá.

   • Se o gerenciamento se recusar, com base na experiência anterior, apenas aumentará a experiência ruim, pois o produto carece de documentação, mas foram gastos alguns meses para escrevê-lo e mantê-lo.

A documentação deve ser um processo contínuo, assim como o teste. Passe uma semana simplesmente codificando alguns milhares de LOC, e voltar aos testes e à documentação é muito, muito doloroso.

Como incentivar a equipe a escrever documentação?

De maneira semelhante às formas de incentivar as pessoas a escrever código limpo, refatorar regularmente, usar padrões de design ou adicionar testes de unidade suficientes.

• Lidere pelo exemplo. Se você escrever uma boa documentação, seus pares também poderão começar a fazê-lo.

• Faça revisões sistemáticas de código, incluindo revisões formais de código destinadas a inspecionar a documentação.

• Se alguns membros da equipe são particularmente antipáticos a uma boa documentação (ou documentação), discuta o assunto com eles em particular, para entender quais são os impedimentos que os impedem de escrever uma melhor documentação. Se eles culparem a falta de tempo, você verá a fonte dos problemas.

• Torne a presença ou a falta de documentação mensurável por algumas semanas ou meses, mas não se concentre nisso. Por exemplo, você pode medir o número de linhas de comentários por LOC, mas não faça uma medida permanente; caso contrário, os desenvolvedores começarão a escrever comentários longos, mas sem sentido, apenas para se livrar de pontuações baixas.

• Use gamification. Isso vem junto com o ponto anterior.

• Use reforço positivo / negativo .

• (Veja o comentário de SJuan76 ) Trate a falta de comentários como erros. Por exemplo, no Visual Studio, você pode verificar uma opção para gerar documentação XML. Se você também verificar se todos os avisos são tratados como erros, a falta de um comentário no topo de uma classe ou de um método interromperá a compilação.

  Quanto aos três pontos anteriores, este deve ser usado com cautela. Eu usei isso por um tempo com uma equipe particularmente difícil de programadores iniciantes, e acabou com comentários compatíveis com StyleCop como:

    /// <summary>
    /// Gets or sets the PrimaryHandling.
    /// </summary>
    public Workflow PrimaryHandling { get; set; }

que foram, hm ..., não são particularmente úteis.

Lembre-se: nada automatizado pode ajudá-lo a identificar comentários ruins quando os programadores querem se meter com você . Somente revisões de código e outras tarefas humanas ajudarão.

Existem bons exemplos de quando é necessária uma documentação mínima ou nenhuma?

Não é necessária documentação que explique a arquitetura e o design :

• Para um protótipo,

• Para um projeto pessoal escrito em poucas horas para realizar uma tarefa, embora tenha certeza de que esse projeto não será mais mantido,

• Para qualquer projeto em que seja óbvio, dado o tamanho pequeno, juntamente com o código particularmente limpo, você passará mais tempo escrevendo documentação do que todos os futuros mantenedores que exploram o código.

A documentação no código (comentários de código) não é necessária, de acordo com alguns desenvolvedores, quando o código é auto-documentado. Para eles, a presença de comentários não é, exceto nos casos raros, um bom sinal, mas um sinal de que o código não foi refatorado o suficiente para ser claro sem a necessidade de comentários.

Sinto que devemos ter uma revisão da documentação após a entrega de um projeto.

Se o seu projeto for entregue pelo menos uma vez por semana, é o caminho a percorrer. Se o seu projeto não for ágil e for entregue a intervalos de seis meses, faça revisões mais regulares.

Eu acho que você deve fazer uma distinção entre comentários e documentação. Embora os comentários sejam descritivos, eles não têm consistência, estão espalhados por todo o código. Os comentários nunca devem compensar o código que não é auto-descritivo o suficiente, mas devem sugerir outros programadores em partes complicadas.

Se o código deve ser documentado depende da escala do projeto. Certamente, existem pessoas que acreditam que tudo deve ser documentado, e parece fácil justificar esse pensamento, porque quem ousaria se opor à documentação do conhecimento? Felizmente, o desenvolvimento de software não é ciência e o mundo não entra em colapso se os detalhes por trás de seu pequeno programa se tornarem obscuros. Agora, com relação a um software profissional para uso de muitos desenvolvedores, sim, obviamente você deve documentar seu código. Mas se você estiver em posição de codificar nesse nível, obviamente saberia disso.

tl; dr

Se você está pedindo que cada projeto seja bem documentado, está pedindo demais.