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.
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.
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.
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:
No início, a equipe está disposta a documentar muito.
Com o tempo, a pressão dos prazos e a falta de interesse tornam cada vez mais difícil manter a documentação.
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.
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.