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


26

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?


2
Há outra razão pela qual geralmente não existe documentação adequada: é muito difícil escrever uma boa documentação que não apenas parafraseie o código em inglês, mas descreva por que o código foi projetado / escrito dessa maneira. A necessidade dessas informações se torna óbvia apenas meses depois de terem sido anotadas.
Bart van Ingen Schenau

1
Outro motivo sério: muitos desenvolvedores têm o inglês como segunda língua e / ou escrevem mal o inglês. Você pode apenas forçá-los a escrever uma linha para um método, mas se você deseja uma boa documentação, é melhor estar preparado para pagar por ela e contratar especialistas para fazê-la.
David.pfx

Respostas:


26

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.


Para 'como incentivar', eu acrescentaria que muitos IDEs permitem a notificação de documentação ausente como avisos. Como alternativa, talvez uma análise estática da documentação possa ser feita no OSB (claro, isso por si só não seria suficiente).
precisa saber é

@ SJuan76: De fato. O Visual Studio pode até tratar a falta de comentários como um erro em tempo de compilação. Eu editei minha resposta para adicionar uma observação sobre isso.
Arseni Mourzenko

@ArseniMourzenko - Li que poderíamos incentivar alguma documentação no Agile adicionando histórias para documentação. Porém, eles não devem bloquear as outras histórias, ou seja, outras definições de histórias concluídas, não devem incluir a conclusão das histórias da documentação. Como isso soa?
Borat Sagdiyev 30/01

3

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.


2
Fortunately software development is not sciencePor favor, conte-me mais sobre por que você acredita nisso.
Borat Sagdiyev

3
@Borat - O desenvolvimento de software é uma disciplina de engenharia, o que implica que ele utiliza as ferramentas fornecidas pela ciência.
Leopold Asperger

Não estou pedindo que tudo seja documentado. Deve ser apenas o suficiente para fornecer uma visão geral de alto nível do que um sistema e código fazem. Por exemplo. Por favor, diga-me como usar minha TV. Não me importo se ele usa LCD, CRT, tubos de vácuo ou dispositivos de estado sólido para fazer o trabalho. Se um técnico desejar essas informações, faça uma documentação separada para ele.
Borat Sagdiyev

Se você deseja uma visão geral de alto nível, os nomes dos identificadores são suficientes. Assim como o botão na sua TV pode ter um rótulo "Ativado". Então você está pedindo detalhes de baixo nível.
Leopold Asperger

2
@LeopoldAsperger: Acho que Borat está falando sobre documentar arquitetura e design, não métodos em classes.
Arseni Mourzenko
Ao utilizar nosso site, você reconhece que leu e compreendeu nossa Política de Cookies e nossa Política de Privacidade.
Licensed under cc by-sa 3.0 with attribution required.