Como fazer a documentação do código e por que o software (frequentemente) é mal documentado?

Como documentar o código?

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

De maneira mais geral, não há um conjunto único 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édio porte .

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

Porque a maioria dos projetos de código aberto são feitos por pessoas que contribuem para esses projetos porque é divertido. A maioria dos programadores e desenvolvedores considera que escrever documentação não é divertido o suficiente para ser feito gratuitamente.

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

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

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

2. O lo O custo do prazo (custo de manutenção da documentação) torna-se bastante fácil também para os gerentes, e muitas vezes é o primeiro alvo quando eles devem reduzir o custo ou diminuir os atrasos. Isso causa um problema adicional de documentação desatualizada que rapidamente se torna inútil e é extremamente caro para atualizar.

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

O que costumo observar é 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 a manutenção da documentação.

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

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

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

   • Se a gerência se recusar, com base na experiência anterior, isso só aumenta a experiência ruim, já que o produto não tem documentação, mas alguns meses foram gastos para escrevê-la e mantê-la.

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 encorajar a equipe a escrever documentação?

Da mesma forma que as maneiras 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 podem começar a fazer isso também.

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

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

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

• Use a gamificação. Isso vem junto com o ponto anterior.

• Use positivo / negativo reforço .

• (Veja o comentário de SJuan76 ) Trate a falta de comentários como erros. Por exemplo, no Visual Studio, você pode marcar 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 início de uma classe ou de um método irá interromper a compilação.

  Quanto aos três pontos anteriores, este deve ser usado com cuidado. Usei-o por um tempo com uma equipe particularmente difícil de programadores iniciantes, e acabou com comentários em conformidade com o StyleCop como este:

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

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

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

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

A documentação explicando a arquitetura e o design não é necessária:

• 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 onde seja óbvio, dado o tamanho pequeno dele, juntamente com o código particularmente limpo, que você gastará mais tempo escrevendo documentação do que todos os futuros mantenedores explorando o código.

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

Acho que devemos fazer uma revisão da documentação após a entrega do projeto.

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

Comentários

• Para ‘ como encorajar ‘, eu acrescentaria que muitos IDEs permitem a notificação de documentos ausentes como avisos. Alternativamente, talvez uma análise estática da documentação possa ser feita no OSB (é claro, isso por si só não seria suficiente).
• @ SJuan76: De fato. O Visual Studio pode até tratar a falta de comentários como um erro de tempo de compilação. Editei minha resposta para adicionar uma observação sobre isso.
• @ArseniMourzenko – eu li que poderíamos encorajar alguma documentação no Agile adicionando histórias para documentação. Mas, isso não deve bloquear as outras histórias, ou seja, a definição de outras histórias de pronto, não deve incluir a conclusão de histórias de documentação. O que acha disso?
• @ArseniMourzenko – Eu ‘ gostaria de adicionar mais dois pontos à sua resposta. (1) Em Jira etc., adicione uma tarefa para documentação o tempo todo. (2) Faça com que quaisquer documentos sejam revisados por mais 2 pessoas & coloque isso como uma tarefa também. Dessa forma, as pessoas serão lembradas de documentar & para evitar a gravação de documentos de baixa qualidade (devido à revisão). Se você não ‘ não priorizá-lo & revê-lo, ele se tornará ruim. Eu sei que a Amazon faz muitas & revisões de documentos, talvez até demais.

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, mas estão espalhados por todo o código. Os comentários nunca devem compensar o código que não é autodescritivo o suficiente; em vez disso, devem indicar a outros programadores as 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 documentando conhecimento? Felizmente, o desenvolvimento de software não é ciência e o mundo não entrará em colapso se os detalhes por trás de seu pequeno programa se tornarem obscuros. Agora, em relação a um software profissional para uso por muitos desenvolvedores, sim, obviamente, você deve documentar seu código. para codificar nesse nível, então você obviamente saberia disso.

tl; dr

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

Comentários

• Fortunately software development is not science Conte-me mais sobre por que você acredita nisso.
• @Borat – O desenvolvimento de software é uma disciplina de engenharia, o que implica que ela usa as ferramentas fornecidas pela ciência.
• Não estou pedindo que tudo seja documentado. Deveria ser apenas o suficiente para fornecer uma visão geral de alto nível do que um sistema e código fazem. Por exemplo, diga-me como usar minha TV. Não ‘ me importo se ela usa LCD, CRT Tubos de vácuo ou dispositivos de estado sólido para fazer o trabalho . Se um reparador deseja essa informação, faça uma documentação separada para ele.
• Se você deseja uma visão geral de alto nível, então os nomes de identificador são suficientes. Assim como o botão em sua TV pode ter um rótulo ” On “. Então, você está pedindo detalhes de baixo nível.
• @LeopoldAsperger: Acho que Borat está falando sobre documentar arquitetura e design, não métodos em classes.