Existe algum motivo lógico para gerar automaticamente a documentação do código? [fechadas]

A geração automática de documentação pode ser feita com uma variedade de ferramentas, sendo o GhostDoc um dos mais importantes. No entanto, por definição, tudo o que gera é redundante. Ele examina os nomes dos métodos, classes, etc. e produz o inglês que pode explicá-los mais detalhadamente. Na melhor das hipóteses, ele faz o que o leitor já poderia fazer na cabeça deles (exemplos extraídos daqui ):

/// <summary>
/// Initializes a new instance of the <see cref="Person"/> class.
/// </summary>
public Person() ...

Na pior das hipóteses, ele pode acabar gerando documentação bizarra que é realmente enganosa na tentativa de descobrir heuristicamente o significado dos nomes:

/// <summary>
/// Riches the text selection changed.
/// </summary>
/// <param name="richTextBox">The rich text box.</param>
private void RichTextSelection_Changed(System.Windows.Controls.RichTextBox richTextBox) ...

Parece que a atitude do GhostDoc é "é intrinsecamente melhor ter algum tipo de documentação XML formal", mas quando essa documentação é 100% redundante, por quê? Não é apenas desperdiçar uma tonelada de espaço na melhor das hipóteses?

No meu local de trabalho, precisamos documentar tudo, e quase sempre com os documentos gerados automaticamente pelo GhostDoc. Você faz isso e existem razões racionais para não deixar o código simplesmente sem documentos, se você realmente não escrever a documentação?

[...] documente tudo e quase sempre com os documentos gerados automaticamente pelo GhostDoc. Você faz isso e existem razões racionais para não deixar o código simplesmente sem documentos, se você realmente não escrever a documentação?

Não. A documentação gerada pelo GhostDoc é padronizada (semelhante à criação de uma nova classe OO em um IDE cria a padronização para uma classe com um construtor ou algo assim). A parte útil da documentação é o que se seguiria após a adição do padrão.

Enquanto você precisa documentar tudo no local de trabalho, parece que seus colegas encontraram a maneira perfeita de contornar isso: apenas finja.

Em uma linguagem de tipo estaticamente, a documentação no estilo Javadoc não é para os autores, é para os consumidores. A geração automática simplesmente facilita para os autores manter a documentação para outras pessoas consumirem.

Se você estiver usando uma linguagem de tipo estaticamente e não estiver escrevendo uma biblioteca para consumo de terceiros, a geração automática não comprará muito e, na minha experiência, raramente é usada. Se você estiver usando uma linguagem de tipo dinâmico, a documentação no estilo javadoc é frequentemente usada para documentar os tipos, mesmo para uso interno, mas a geração automática não conhece os tipos, portanto, tudo o que economiza é evitar a cópia manual do padrão.

De qualquer maneira, não pense na geração automática como produzindo um produto acabado. Pense nisso como produzindo o padrão para você, para que quaisquer alterações feitas manualmente sejam significativas.

Existe algum motivo lógico para gerar automaticamente a documentação do código?

Da perspectiva de quem?

Se eu estava dirigindo a empresa ou o grupo de desenvolvedores, não há uma boa razão. Estou firmemente no campo "os comentários devem explicar o porquê ". Forçar as pessoas a comentar classes / funções / propriedades é pior do que inútil, uma vez que ficam desatualizadas, enganam o leitor, são usadas como desculpa para não criar código legível, e assim por diante. Esses comentários perdem tempo escrevendo-os, lendo o código e erros causados ​​por eles. Alguns argumentam que os documentos da API do estilo JavaDoc são um motivo para fazer os comentários, mas mesmo com esse argumento, uma pequena parte do seu código deve fazer parte da API pública, e o JavaDoc não substitui os documentos da API reais.

Como desenvolvedor, trabalhei em alguns lugares que exigem comentários nesses locais, apesar da minha opinião. Como não tenho tempo nem paciência para escrever um monte de porcaria que ninguém vai usar, eu o GhostDoc. Isso me permite gastar esse tempo realmente fazendo coisas importantes. Muito mais eficiente do que mudar a política corporativa.

Outra coisa boa que encontrei usando o GhostDoc é que ele serve para verificar se meus nomes são bons. Se o GhostDoc não puder gerar documentação decente para uma função, é um cheiro que meus nomes de função ou parâmetro possam estar ruins. Embora eu não usasse a ferramenta apenas para isso, é um pequeno efeito colateral agradável se eu estiver sendo obrigado a perder meu tempo de qualquer maneira.

Edição : Eu não entendi a pergunta original; Embora eu acho que a geração de documentação (ou seja, não-código documentos ) podem ser extremamente valiosos (ver resposta original sobre Doxygen abaixo), geradoras de auto comentários (que é algo que realmente faz GhostDoc) parece loucura para mim. Não consigo entender por que alguém esperaria que um programa pudesse ler código-fonte não comentado e escrever comentários que o esclarecessem genuinamente.

É concebível para mim que um utilitário de geração de comentários extremamente "inteligente" possa ser programado para reconhecer certos padrões e gerar comentários no estilo "como"; por exemplo, ele poderia reconhecer o algoritmo de cálculo de variância de Knuth e fornecer um comentário explicando como ele funciona e por que o algoritmo ingênuo não seria apropriado. Talvez esse utilitário possa até ser programado para reconhecer padrões de design canônicos orientados a objetos (por exemplo, Abstract Factory) e inserir comentários indicando qual padrão está sendo usado e quais classes estão desempenhando quais papéis.

Mas, na minha opinião, os comentários mais úteis não explicam "como" algo funciona, pois o próprio código deve mostrar isso, mas " por que " comenta, explicando "por que" uma coisa específica está sendo feita. Conforme observado por David Hammen nos comentários abaixo, para gerar comentários "por que", um utilitário precisaria "ler a mente do programador". Obviamente isso é impossível.

Com base nos exemplos apresentados, no entanto, parece que o GhostDoc nem realiza a tarefa de criar verdadeiros comentários no estilo "como". Por isso, é, na minha opinião, mais do que inútil, uma vez que ele não gerar pode ser inane e enganosa (como no segundo exemplo).

Resposta original: por que a extração e formatação automáticas de documentação é uma boa idéia

Minha equipe de software usa o Doxygen. A principal razão para isso é que precisamos de documentação que não seja de código-fonte (ou seja, legível por não programadores) de recursos de código / comportamento / etc, mas achamos que é uma prática melhor integrá-la ao próprio código-fonte do que mantenha-o como um segundo documento . Isso nos ajuda a manter a documentação sincronizada com o código-fonte (embora, é claro, isso nunca possa ser completamente garantido, muito menos automatizado) e minimiza a sobrecarga de escrever documentação (uma vez que a documentação de um trecho de código pode ser incorporada trivialmente no arquivo que contém o próprio código).

Portanto, o foco do nosso uso de Doxygen não é extrair informações do próprio código, mas manter a documentação do código-fonte o mais próximo possível do próprio código-fonte.

Isso também nos permite usar uma única ferramenta para criar uma "teoria das operações" que descreve toda a nossa base de código e vários conjuntos de "notas de versão" que descrevem o produto de software, mas na verdade não contêm nenhuma "documentação de código" real no senso típico.

Quanto ao motivo pelo qual precisaríamos de documentação que não seja de código-fonte do comportamento de nosso código, há dois motivos:

• Nosso produto não é apenas software; é uma ferramenta complexa que integra muitos componentes de hardware, incluindo alguns lasers e fluidos sofisticados. Precisamos de engenheiros sem muita experiência em software para entendermos exatamente como os componentes internos do nosso código se comportam e dizer a eles "leia o código-fonte" não vai conseguir isso.
• Devemos seguir algumas regulamentações de qualidade, algumas exigidas internamente pela empresa e outras legalmente exigidas pelo governo federal. Embora o processo de qualidade seja (ou pelo menos possa ser) extremamente valioso e útil, envolve uma quantidade não negligenciável de sobrecarga, parte da qual é dever da equipe de software fornecer esse tipo de documentação detalhada do software. Novamente, a integração desta documentação com o próprio código minimiza a sobrecarga e nos ajuda a manter a documentação atualizada.

Observe que o segundo ponto é bastante semelhante ao que algumas outras respostas fizeram sobre os gerentes que desejam a garantia (/ direito de se gabar) de saber que existe alguma documentação (independentemente da qualidade) para cada parte do código-fonte; essa maneira de enquadrá-lo, no entanto, ignora o fato de que a documentação solicitada externamente pode realmente ter algumas vantagens legítimas.

Certamente, a documentação automatizada é particularmente útil quando é possível reproduzir descrições criteriosas e apropriadas, escritas pelos autores do código. Caso contrário, é apenas um formatador automático glorificado.

Mas a formatação não é inútil. Existe um valor em ser capaz de encontrar os métodos públicos de um componente grandioso de uma só vez, classificado e com garantia de que está completo. Se você precisa de um frobnickmutador, e ele não está lá, você sabe que não está lá sem percorrer o código-fonte. (Os resultados negativos também têm valor: você sabe que precisa fazer alguma coisa e tem mais tempo para fazê-lo, porque não precisou andar.)

Portanto, sim, a geração automática de documentos agrega algum valor. Certamente não tanto quanto os gerentes provavelmente supõem, e geralmente nem tanto quanto um editor de cópias realmente bom, mas não nada.

Nesta forma, é pior do que inútil, mas apenas porque depende apenas da assinatura pública (que, no caso do Javadoc, é visível de qualquer maneira para qualquer pessoa que esteja lendo o documento da API).

Mas é possível escrever ferramentas de documentação automatizadas que considerem o corpo do método também. Como prova de conceito, escrevi um pequeno plug-in do Eclipse que adiciona uma lista de outros métodos chamados do método documentado ao Javadoc. (Nem todas as chamadas, é claro, você pode definir filtros, por pacote, por exemplo.)

E, na verdade, achei bastante útil ao mapear mentalmente uma base de código completamente desconhecida. É um caso de uso muito limitado, mas definitivamente foi uma ajuda.

Com base nessa experiência, a resposta para a pergunta é: sim, mas precisamos de ferramentas muito mais inteligentes.

Atualização: Obviamente, uma pergunta adicional (que deve ser feita antes de escrever qualquer tipo de documentação) é quem é o público-alvo. Se estivermos documentando uma API pública para clientes dessa API, adicionar todos esses detalhes de implementação é um grande não-não, pois tudo o que você coloca no Javadoc é tecnicamente parte da API.

Porém, se o público-alvo tiver outros desenvolvedores trabalhando no mesmo produto, adicionar automaticamente informações sobre detalhes da implementação, como quais métodos modificam ou lêem um determinado campo, é aceitável e bastante útil.

Eu não conheço outros ambientes, mas quando se trata de projetos PHP grandes (geralmente de código aberto) que outras pessoas escreveram, o phpXRef é um salva-vidas absoluto (especialmente se o documento for colocado online e o Google puder indexá-lo).

Mesmo um projeto mal comentado pode pelo menos me ajudar a rastrear onde as coisas foram definidas e onde são usadas (por exemplo, ao refatorar).

Quando bem comentadas, as páginas resultantes se aproximam de uma Bíblia perfeita para a base de código (para meus usos de qualquer maneira).

Além disso, meu IDE preferido gerará automaticamente o bloco de comentários (se eu digitar / **), que executa aproximadamente 75% dos comentários para mim. É incrível quantas coisas estúpidas eu parei de cometer ao longo da minha vida de codificador apenas porque tive que explicar para outras pessoas (e para o futuro) o que estou fazendo. Quando meu comentário para o gerador de documentos é maior que o método, isso geralmente significa que eu não tomei café suficiente e talvez queira pensar um pouco mais.

Esses mesmos blocos de comentários também criam o texto de "ajuda" de conclusão em linha para que eu possa ver exatamente o que era esperado (pelos outros codificadores) enquanto escrevia a chamada de função. Este é um enorme aumento de produtividade para mim (especialmente naqueles casos raros em que outros desenvolvedores úteis escreveram "pelo amor de Deus, faça / não faça X" - o que pode economizar muita dor.

Não posso enfatizar o suficiente como é útil ter os tipos de entrada esperados especificados em projetos PHP complexos (e frequentemente mal nomeados) e a ordem dos argumentos nos métodos menos usados. Mesmo com meu próprio código, nem sempre consigo lembrar quais argumentos especifiquei para algo que não toquei em uma época.

Em um exemplo, significava que a fonte dos problemas recorrentes era que, por algum motivo que reflete mal em desenvolvedores anteriores, algumas funções e até constantes foram definidas em um grande número de lugares (com um grau de inconsistência para adicionar "diversão") . Esse era o sinal para se afastar do projeto.

Em projetos maiores que começaram antes de eu entrar, posso ver qual desenvolvedor (supondo que eles tenham marcado o arquivo da classe com um nome e um email) criou a classe e simplesmente poder encontrar e conversar com o desenvolvedor certo é extremamente útil.

Listas de tarefas automáticas - usar a tag @todo (comum nos tipos de projetos em que trabalho) significa que a documentação pode acompanhar as coisas que precisam de mais trabalho (ou os recursos que faltam). Mais uma vez, meu IDE acompanha isso e isso por si só atua como um bom guia sobre o que precisa primeiro de minha atenção.

Por fim (e muito importante para mim), ele remove a sobrecarga não trivial de escrever tudo isso e, em seguida, tenta mantê-lo atualizado quando alguns (muitos leitores) cometem alterações e não conversam com os mantenedores da documentação.

Portanto, os motivos incluem:

• Economizando para desenvolvedores posteriores uma pilha de tempo,
• Mantendo o controle de onde as funções são chamadas (e definidas),
• Detecção de codificação boba,
• Encontrar (como outro apontou) quando algo está obviamente faltando,
• Simplificando a refatoração (nunca é muito divertido)
• (Em muitos casos), ter uma idéia do que o desenvolvedor estava tentando fazer (supondo que ele tenha deixado algumas anotações).
• Se o projeto for complexo o suficiente para ter várias licenças em andamento (sem graça), posso ver rapidamente quais licenças se aplicam a qualquer seção. É certo que este é um bônus adicional.
• Obtendo uma idéia de com quem conversar sobre um arquivo de projeto.
• Listas de tarefas automáticas

Além disso, não subestime o valor de manter os chefes de cabelos pontudos felizes com o toque de um botão.

Em suma, os "comentários da documentação automática" são vitais para meus hábitos de codificação. Tenho certeza de que muitos pensam que isso é manco, mas também tenho a certeza de que existem poucas pessoas que sabem exatamente o que estou dizendo. Não sei como sobrevivi antes de descobrir o phpXRef (e meu IDE favorito).

Geralmente, é bom usar geradores de documentação para criar comentários padronizados ou "substitutos" que são posteriormente revisados ​​pelos desenvolvedores reais. Costumo usar a função auto-JavaDoc do Eclipse para gerar o comentário do cabeçalho com tipos de parâmetros e retornar valores já preenchidos e, em seguida, simplesmente adicionar a "descrição" da documentação.

Como desenvolvedor de C #, uso o Stylecop, que exige comentários para todas as classes, métodos etc. Eu gero esses comentários automaticamente usando uma ferramenta. Na maioria das vezes, os comentários gerados pela ferramenta são suficientes e podem ser inferidos pelo nome do objeto, por exemplo, uma classe Person e um campo de ID.

Mas, se eu quiser comentar um método não óbvio, é muito fácil expandir a documentação padrão e algumas explicações sobre o que ele faz. Como exemplo: eu tenho um método na minha classe Person, que retorna FirstName + Lastname, mas adicionei um pouco de documentação sobre o que está acontecendo quando um dos dois está ausente.

Resumindo: acho que o documento padronizado pode ser prejudicial se você nunca alterar o texto fornecido pelo gerador. Nesse caso, é apenas ruído de linha. Mas se você os vir como um modelo, eles abaixam os padrões para fornecer comentários bons e úteis para você ou seus consumidores. Você poderia escrever os comentários sem gerá-los automaticamente? Claro, mas você teria que respeitar o formato (que no caso de C # é bastante detalhado e irritante para gerar manualmente) e isso reduz a chance de você realmente fornecer esse comentário.

Evitar Tautologia

O único momento em que você precisa de qualquer tipo de documentação para o código é explicar por que um método / função está fazendo alguma coisa; o nome deve ser suficiente para o que está fazendo.

Se você estiver fazendo algo que não é idiomático ou viole o princípio de menor espanto , é necessária documentação.

A documentação gerada automaticamente, que é apenas um formatador para saída de informações, é quase exigida pelos consumidores do seu código. Javadoc faz isso extremamente bem.

Nem tudo deve ser documentado manualmente

Coisas como os métodos getXXX / setXXX devem ser auto-explicativas; assim, a documentação de geração automática que permite que você saiba que ela existe será bem recebida.

A documentação do código, pelo menos do tipo "automático", representa o denominador menos comum para as pessoas que tentam entender o aplicativo.

Os usuários mais sofisticados não gostariam da documentação automática do código. Eles preferem ter "alvejado" a documentação que lhes diz o que (pouco) eles precisam ser informados.

Os usuários menos sofisticados não o apreciariam pelo motivo oposto; eles não entenderiam de qualquer maneira.

Os usuários mais "agradecidos" da documentação automática de códigos são aqueles para quem "um pouco de conhecimento" é uma coisa perigosa. "Eles podem ou não entender a documentação (embora provavelmente o façam), mas se sentirão bem em" ser "Este público-alvo inclui a maioria dos tipos" gerenciais ". Se esse for o seu público-alvo principal, a documentação automática de código pode ser uma boa coisa.

a resposta simples para "por que gerar documentos" pode ser simplesmente respondida mostrando o MSDN.

Imagine tentar escrever um programa que use qualquer biblioteca em que não haja documentação da API. Seria um pesadelo. O MSDN é um ótimo exemplo do tipo de documento que pode ser gerado a partir do código-fonte e dos comentários e constitui um recurso essencial para os desenvolvedores.

Se você estiver escrevendo um aplicativo (ou seja, não uma biblioteca para ser consumida por outras pessoas), talvez haja um motivo para não se incomodar - mas mesmo assim, quanto de um aplicativo grande, somente interno, não contém várias bibliotecas de qualquer forma? Quando você ingressa em uma equipe, ter algum documento da API navegável será útil.

Nenhuma ferramenta irá escrever sua documentação para você, mas elas fornecem o padrão que você teria que escrever manualmente de qualquer maneira, algumas ferramentas (como doxygen) também geram diagramas e listas de referência (de funções de chamada e chamada, por exemplo ) que não seriam facilmente descobertos, mesmo olhando o código-fonte.

Obviamente, o bom senso pragmático deve ser aplicado ao que é documentado, propriedades e funções secundárias podem ser ignoradas (e ignoradas da geração, mesmo nas ferramentas), mas em nenhum momento alguém deve dizer "existe o código fonte, já é documentação suficiente" a qualquer momento .