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

59

A geração automática de documentação pode ser feita com uma variedade de ferramentas, sendo o GhostDoc um dos mais proeminentes. No entanto, por definição, tudo o que gera é redundante. Ele dá uma olhada nos nomes dos métodos, classes, etc. e produz o inglês que pode explicá-los de forma mais detalhada. Na melhor das hipóteses, ele faz o que o leitor já poderia fazer em sua cabeça (exemplos retirados de http://taswar.zeytinsoft.com/2013/12/02/documentation-comment-c-code-use -ghostdoc-less / "> aqui ):

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

Na pior das hipóteses, pode acabar gerando documentação bizarra que na verdade é enganosa em sua 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 com o GhostDoc é, "é intrinsecamente melhor ter algum tipo de documentação XML formal", mas quando essa documentação é 100% redundante, por quê? Não é só perder muito espaço na melhor das hipóteses?

No meu local de trabalho, temos que documentar tudo e quase sempre com os documentos gerados automaticamente do GhostDoc. Você faz isso, e existem razões racionais para não deixar o código em situação irregular se você não for realmente escrever a documentação?

    
por Jez 08.09.2014 / 17:08
fonte

12 respostas

13

[...] document everything, and almost always with GhostDoc's auto-generated docs. Do you do this, and are there any rational reasons not to simply leave code undocumented if you aren't going to actually write the documentation yourself?

Não. A documentação gerada pelo GhostDoc é clichê (semelhante a como criar uma nova classe OO em um IDE cria o boileplate para uma classe com um construtor ou algo assim). A parte útil da documentação é o que seguiria depois de adicionar o clichê.

Enquanto você tem que documentar tudo no seu local de trabalho, parece que seus colegas descobriram o caminho perfeito: apenas finja.

    
por 09.09.2014 / 10:52
fonte
71

Em uma linguagem com tipagem estática, a documentação no estilo Javadoc não é para os autores, é para os consumidores. A autogeração simplesmente torna mais fácil para os autores manterem a documentação para outras pessoas consumirem.

Se você usa um idioma com tipagem estática e não está escrevendo uma biblioteca para consumo de terceiros, a autogeração não compra muito e, na minha experiência, raramente é usada. Se você estiver usando uma linguagem tipada dinamicamente, a documentação no estilo javadoc é usada para documentar os tipos, mesmo para uso interno, mas a autogeração não conhece os tipos, então tudo o que você economiza é evitar a cópia manual do clichê.

De qualquer forma, não pense em autogeração como produzindo um produto acabado. Pense nisso como produzindo o clichê para você, portanto, quaisquer alterações feitas manualmente são significativas.

    
por 08.09.2014 / 18:02
fonte
26

Is there any logical reason to auto-generate code documentation?

Da perspectiva de quem?

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

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

Uma outra coisa boa que eu encontrei usando o GhostDoc é que ele serve como uma verificação de que meus nomes são bons. Se o GhostDoc não pode gerar documentação decente para uma função, é um cheiro que minha função ou nomes de parâmetro podem ser pobres. Enquanto eu não usaria a ferramenta para apenas isso, é um efeito colateral pouco agradável se eu estou sendo feito para perder meu tempo de qualquer maneira.

    
por 08.09.2014 / 17:29
fonte
21

EDIT : eu não entendi a pergunta original; embora eu ache que gerar documentação (isto é, documentos não-código ) pode ser extremamente valioso (veja a resposta original sobre o Doxygen abaixo), gerando comentários (que é algo que o GhostDoc realmente faz) soa insano 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 realmente o esclarecessem.

É 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"; por exemplo, ele poderia reconhecer o algoritmo de cálculo de variação de Knuth e fornecer um comentário explicando como ele funciona e por que o algoritmo ingênuo não seria apropriado. Talvez tal utilidade possa ser programada para reconhecer padrões de design orientados a objetos canônicos (por exemplo, Abstract Factory) e inserir comentários indicando qual padrão está sendo usado e quais classes estão desempenhando papéis.

Mas, na minha opinião, os comentários mais úteis não explicam "como" algo funciona, já que o próprio código deve mostrar isso, mas " por quê " comentários, explicando "por que" uma coisa em particular está sendo feito. Como observou 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 fornecidos, no entanto, parece que o GhostDoc nem sequer realiza a tarefa de criar verdadeiros comentários no estilo "como". Então, na minha opinião, é pior do que inútil, já que o que ele gera pode ser insano e enganoso (como no segundo exemplo).

Resposta original: por que a documentação automática extração e formatação é uma boa ideia

Minha equipe de software usa o Doxygen. A principal razão para isso é que precisamos de uma documentação de código-fonte não-de-código (isto é, legível por não-programadores) documentação de recursos de código / comportamento / etc, mas nós sentimos que é uma prática melhor para integrar isso no próprio código-fonte do que mantê-lo como um segundo documento . Isso nos ajuda a manter a documentação em sincronia com o código-fonte (embora, é claro, isso nunca seja completamente garantido, muito menos automatizado) e minimiza a sobrecarga da documentação escrita (já que a documentação de um trecho de código pode ser incorporada arquivo contendo o próprio código).

Assim, o foco do nosso uso do 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 de operações" que descreva toda a nossa base de código e vários conjuntos de "notas de lançamento" que descrevem o produto de software, mas na verdade não contêm nenhuma "documentação de código" "no sentido típico.

Quanto ao motivo pelo qual precisaríamos de documentação sem código de origem do comportamento de nosso código, há dois motivos:

  • Nosso produto não é meramente 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 ter uma boa compreensão de exatamente como os componentes internos de nosso código se comportam, e dizer a eles "ler o código-fonte" não conseguirá isso.
  • Precisamos 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, ele 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. Mais uma vez, a integração desta documentação com o próprio código minimiza a sobrecarga e nos ajuda a manter a documentação atualizada.

Note que o segundo ponto é bem parecido com o ponto que algumas outras respostas fizeram sobre os gerentes quererem a garantia (/ direito de se gabar) de saber que alguma documentação (independente da qualidade) existe para cada parte do código-fonte; entretanto, esse modo de enquadramento ignora o fato de que a documentação exigida externamente pode realmente ter algumas vantagens legítimas.

    
por 08.09.2014 / 20:08
fonte
7

Certamente, a documentação automatizada é particularmente útil quando é possível reproduzir descrições perspicazes 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. Há valor em ser capaz de encontrar os métodos públicos de um componente maior em um olhar, classificado e garantido para ser completo. Se você precisar de um frobnick mutator, e ele não estiver lá, você sabe que não está lá sem passar pelo código-fonte. (Resultados negativos também têm valor: você sabe que tem que fazer alguma coisa e tem mais tempo para fazer isso porque não teve que percorrer).

Então, sim, a geração automática de documentos adiciona um valor alguns . Certamente não tanto quanto os gerentes provavelmente supõem, e geralmente nem tanto quanto um editor de texto realmente bom, mas não nada.

    
por 08.09.2014 / 17:13
fonte
6

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

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

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

Além disso, meu IDE preferencial gerará automaticamente o bloco de comentários (se eu digitar / **), o que faz aproximadamente 75% do trabalho de comentários para mim. É incrível como muitas coisas estúpidas foram impedidas de me comprometer com minha vida de codificador só porque tive que explicar a outras pessoas (e a mim) o que estou fazendo. Quando meu comentário para o gerador de doc é maior do 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ário também criam o texto "help" de conclusão in-line para que eu possa ver exatamente o que era esperado pelos outros codificadores enquanto estou escrevendo a chamada de função. Este é um enorme aumento de produtividade para mim (especialmente naqueles raros casos em que algum outro desenvolvedor prestativo escreveu "pelo amor de Deus fazer / não fazer X", o que pode poupar muita dor.

Eu não posso enfatizar o quão útil é ter os tipos de entrada esperados especificados em projetos PHP complexos (e freqüentemente mal nomeados) e a ordem de argumento em métodos menos freqüentemente usados. Mesmo com o meu próprio código, nem sempre consigo lembrar quais argumentos eu especifiquei para algo que não toquei em uma idade.

Em uma instância, isso significou que a razão para os problemas recorrentes foi que, por alguma razão, isso reflete mal nos 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 foi o sinal para se afastar do projeto.

Então, razões incluem salvar desenvolvedores posteriores uma pilha de tempo, manter o controle de onde as funções são chamadas (e definidas), localizar códigos tolos, encontrar (como outro apontou) quando algo está obviamente faltando, simplificando a refatoração (nunca muito divertido ) e em muitos casos, ter uma ideia do que o desenvolvedor estava tentando fazer (assumindo que ele ou ela deixou algumas anotações).

Se o projeto for complexo o suficiente para ter várias licenças em andamento (não é divertido), posso ver rapidamente quais licenças se aplicam a qualquer seção específica. É certo que este é um bônus extra.

Em projetos maiores que começaram antes de entrar, eu posso ver qual desenvolvedor (assumindo que eles marcaram o arquivo de classe com um nome e email) criou a classe e simplesmente ser capaz de encontrar e conversar com o desenvolvedor certo é extremamente útil. / p>

Listas de tarefas automáticas - usar a tag @todo (comum nos tipos de projetos em que estou trabalhando) significa que a documentação pode rastrear coisas que precisam de mais algum trabalho (ou recursos que estão ausentes). Mais uma vez, minha IDE acompanha isso e isso, por si só, funciona como um bom guia para o que precisa da minha atenção primeiro.

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

Por último (e muito importante para mim), ele remove a sobrecarga não-trivial de escrever tudo isso e, em seguida, tentar mantê-lo atualizado quando alguns (ler muitos) codificadores confirmarem alterações e não falarem com os mantenedores de documentação .

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

    
por 09.09.2014 / 06:39
fonte
6

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

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

E eu realmente achei bastante útil quando mapeio mentalmente uma base de código completamente desconhecida. Concedido, é um caso de uso muito limitado, mas foi definitivamente uma ajuda.

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

Atualização: É claro que 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 todo esse detalhe de implementação é um grande não-não, já que qualquer coisa que você coloca no Javadoc é tecnicamente parte da API.

Mas se o público-alvo for outro desenvolvedor trabalhando no mesmo produto, adicionar automaticamente informações sobre detalhes de implementação, como quais métodos modificar ou ler um determinado campo, é aceitável e bastante útil.

    
por 09.09.2014 / 13:21
fonte
4

Geralmente é bom usar geradores de documentação para criar comentários padronizados ou "stand-in" que são posteriormente revisados por desenvolvedores reais. Costumo usar a função auto-JavaDoc do Eclipse para gerar o comentário de cabeçalho com tipos de parâmetro e valores de retorno já preenchidos e, em seguida, simplesmente adicione a "carne" da documentação.

    
por 08.09.2014 / 20:19
fonte
3

Como um desenvolvedor C #, eu uso o Stylecop, que exige comentários para todas as classes, métodos, etc. Eu gero automaticamente esses comentários 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 ex. uma classe Person possui um campo de ID.

Mas se eu quiser comentar mais um método não óbvio, é muito fácil expandir a documentação padrão e algumas explicações sobre o que ela 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á faltando.

Resumindo: acho que o documento padrão pode ser prejudicial se você nunca alterar o texto fornecido pelo gerador. Nesse caso, é apenas ruído de linha. Mas se você vê-los como um modelo, eles diminuem a barra 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 do C # é bastante verboso e chato de gerar à mão) e que diminui a chance de você realmente fornecer este comentário no al ..

    
por 09.09.2014 / 09:39
fonte
3

Evite a Tautologia

A única vez que você deve precisar de qualquer tipo de documentação para 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ê está fazendo algo que não é idiomático, ou viola o princípio de menos espanto então a documentação é necessária.

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

Nem tudo deve ser documentado manualmente

Coisas como os métodos getXXX / setXXX devem ser autoexplicativos, portanto, a documentação de geração automática que apenas informa que eles existem será bem recebida.

    
por 10.09.2014 / 05:44
fonte
2

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

Os usuários mais sofisticados não apreciariam a documentação automática do código. Eles prefeririam ter uma documentação "direcionada" que lhes dissesse o que (pouco) eles precisam saber.

Os usuários menos sofisticados não o apreciam pela razão oposta; eles não entenderiam mesmo assim.

Os usuários mais "apreciativos" da documentação automática de código são aqueles para os quais "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 sobre "ser mantido no loop". Esse público inclui a maioria dos tipos "gerenciais". Se esse é o seu público principal, a documentação do código automático pode ser uma coisa boa.

    
por 08.09.2014 / 21:57
fonte
0

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

Imagine tentar escrever um programa que use qualquer biblioteca onde 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 forma um recurso essencial para os desenvolvedores.

Se você está escrevendo um aplicativo (ou seja, não uma biblioteca para ser consumida por outras pessoas) então talvez exista um caso para não ser incomodado - mas mesmo assim, quanto de um aplicativo grande, somente interno, não contém monte de bibliotecas de qualquer maneira? Quando você se junta a essa equipe, ter algum documento de API navegável será útil.

Nenhuma ferramenta vai escrever sua documentação para você, mas eles lhe dão o clichê que você teria que escrever manualmente de qualquer maneira, algumas ferramentas (como doxygen) também irão gerar diagramas e listas de referência (de chamada e chamada funções, por exemplo) que não seriam facilmente descobertas mesmo observando o código-fonte.

Obviamente, o senso comum 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 deveria dizer "há o código fonte, isso é documentação suficiente" a qualquer momento.

    
por 11.09.2014 / 12:13
fonte