O que é código de auto-documentação e pode substituir código bem documentado? [fechadas]

Eu tenho um colega que insiste que o código dele não precisa de comentários, é "auto-documentável".

Analisei o código dele e, embora seja mais claro que o código que já vi outros produzirem, ainda discordo que o código de auto-documentação seja tão completo e útil quanto o código comentado e documentado.

Ajude-me a entender o ponto de vista dele.

• O que é código de auto-documentação
• Pode realmente substituir o código bem comentado e documentado
• Existem situações em que é melhor do que um código bem documentado e comentado
• Existem exemplos em que o código não pode ser auto-documentado sem comentários

Talvez sejam apenas minhas próprias limitações, mas não vejo como isso pode ser uma boa prática.

Isso não pretende ser um argumento - por favor, não traga razões pelas quais códigos bem comentados e documentados são de alta prioridade - existem muitos recursos mostrando isso, mas eles não são convincentes para o meu colega. Acredito que preciso entender melhor sua perspectiva para convencê-lo do contrário. Inicie uma nova pergunta, se necessário, mas não discuta aqui.

Uau, resposta rápida! Leia todas as respostas existentes e forneça comentários para as respostas em vez de adicionar novas, a menos que sua resposta seja substancialmente diferente de qualquer outra resposta aqui.

Além disso, aqueles de vocês que estão argumentando contra o código de auto-documentação - isso é principalmente para me ajudar a entender a perspectiva (isto é, aspectos positivos) dos evangelistas de código de auto-documentação. Espero que outras pessoas o votem se você não permanecer no tópico.

Na minha opinião, qualquer código deve ser auto-documentado. No código bom e auto-documentado, você não precisa explicar todas as linhas porque cada identificador (variável, método, classe) tem um nome semântico claro . Ter mais comentários do que o necessário torna mais difícil (!) A leitura do código; portanto, se seu colega

• escreve comentários de documentação (Doxygen, JavaDoc, XML, etc.) para cada classe, membro, tipo e método AND
• comenta claramente qualquer parte do código que não seja auto-documentada E
• escreve um comentário para cada bloco de código que explica a intenção ou o que o código faz em um nível de abstração mais alto (por exemplo, encontre todos os arquivos maiores que 10 MB em vez de percorrer todos os arquivos em um diretório, teste se o tamanho do arquivo é maior que 10 MB, rendimento retornado se verdadeiro )

o código e a documentação dele estão bem, na minha opinião. Observe que o código auto-documentado não significa que não deve haver comentários, mas apenas que não deve haver comentários desnecessários. O fato é que, ao ler o código (incluindo comentários e comentários da documentação), deve-se entender imediatamente o que o código faz e por quê. Se o código de "auto-documentação" leva mais tempo para ser compreendido do que o código comentado, não é realmente auto-documentado.

Bem, como se trata de comentários e código, vejamos algum código real. Compare este código típico:

float a, b, c; a=9.81; b=5; c= .5*a*(b^2);

Para este código de auto-documentação, que mostra o que está sendo feito:

const float gravitationalForce = 9.81;
float timeInSeconds = 5;
float displacement = (1 / 2) * gravitationalForce * (timeInSeconds ^ 2);

E depois para este código documentado, que explica melhor por que está sendo feito:

/* compute displacement with Newton's equation x = vₒt + ½at² */
const float gravitationalForce = 9.81;
float timeInSeconds = 5;
float displacement = (1 / 2) * gravitationalForce * (timeInSeconds ^ 2);

E a versão final do código como documentação com zero comentários necessários:

float computeDisplacement(float timeInSeconds) {
    const float gravitationalForce = 9.81;
    float displacement = (1 / 2) * gravitationalForce * (timeInSeconds ^ 2);
    return displacement;
}

Aqui está um exemplo de um estilo de comentário ruim:

const float a = 9.81; //gravitational force
float b = 5; //time in seconds
float c = (1/2)*a*(b^2) //multiply the time and gravity together to get displacement.

No último exemplo, os comentários são usados ​​quando as variáveis ​​devem ter um nome descritivo e os resultados de uma operação são resumidos quando podemos ver claramente o que é a operação. Eu preferiria o segundo exemplo auto-documentado a esse qualquer dia, e talvez seja sobre isso que seu amigo está falando quando diz código auto-documentado.

Eu diria que isso depende do contexto do que você está fazendo. Para mim, o código auto-documentado é provavelmente suficiente neste caso, mas um comentário detalhando a metodologia por trás do que está por trás do feito (neste exemplo, a equação) também é útil.

O código em si sempre será a explicação mais atualizada do que seu código faz, mas, na minha opinião, é muito difícil explicar a intenção , que é o aspecto mais vital dos comentários. Se está escrito corretamente, já sabemos o que o código faz, só precisamos saber por que ele o faz!

Alguém disse uma vez

1) Escreva apenas comentários para códigos difíceis de entender.
2) Tente não escrever um código difícil de entender.

A idéia por trás do código de "auto-documentação" é que a lógica real do programa no código é trivialmente clara o suficiente para explicar a quem lê o código não apenas o que o código está fazendo, mas por que está fazendo.

Na minha opinião, a ideia do verdadeiro código de auto-documentação é um mito. O código pode explicar a lógica por trás do que está acontecendo, mas não explica por que está sendo feito de uma certa maneira, principalmente se houver mais de uma maneira de resolver um problema. Por esse motivo, ele nunca pode substituir um código bem comentado .

Eu acho que é relevante questionar se uma linha de código específica é auto-documentada, mas no final, se você não entender a estrutura e a função de uma parte do código, na maioria das vezes os comentários não ajudarão. Veja, por exemplo, a fatia de código "comentada corretamente" de amdfan:

/* compute displacement with Newton's equation x = v0t + ½at^2 */
const float gravitationalForce = 9.81;
float timeInSeconds = 5;
float displacement = (1 / 2) * gravitationalForce * (timeInSeconds ^ 2);

Esse código é bom, mas o seguinte é igualmente informativo na maioria dos sistemas de software modernos e reconhece explicitamente que o uso de um cálculo newtoniano é uma opção que pode ser alterada caso outro paradigma físico seja mais apropriado:

const float accelerationDueToGravity = 9.81;
float timeInSeconds = 5;
float displacement = NewtonianPhysics.CalculateDisplacement(accelerationDueToGravity, timeInSeconds);

Na minha própria experiência pessoal, existem muito poucas situações de codificação "normais" nas quais você absolutamente precisa de comentários. Com que frequência você acaba lançando seu próprio algoritmo, por exemplo? Basicamente, todo o resto é uma questão de estruturar seu sistema para que um codificador possa compreender as estruturas em uso e as opções que levaram o sistema a usar essas estruturas específicas.

Eu esqueço de onde eu consegui isso, mas:

Todo comentário em um programa é como um pedido de desculpas ao leitor. "Sinto muito que meu código seja tão opaco que você não possa entender olhando para ele". Nós apenas temos que aceitar que não somos perfeitos, mas nos esforçamos para ser perfeitos e pedimos desculpas quando precisamos.

Antes de tudo, é bom saber que o código do seu colega é de fato mais claro do que outro código que você já viu. Isso significa que ele provavelmente não está usando a "auto-documentação" como desculpa por ter preguiça de comentar seu código.

Código de auto-documentação é um código que não requer comentários de texto livre para um leitor informado entender o que está fazendo. Por exemplo, este trecho de código é auto-documentado:

print "Hello, World!"

e é assim:

factorial n = product [1..n]

e é assim:

from BeautifulSoup import BeautifulSoup, Tag

def replace_a_href_with_span(soup):
    links = soup.findAll("a")
    for link in links:
        tag = Tag(soup, "span", [("class", "looksLikeLink")])
        tag.contents = link.contents
        link.replaceWith(tag)

Agora, essa idéia de um "leitor informado" é muito subjetiva e situacional. Se você ou qualquer outra pessoa estiver com problemas para seguir o código do seu colega, convém reavaliar sua ideia de leitor informado. Algum nível de familiaridade com o idioma e as bibliotecas que estão sendo usadas deve ser assumido para chamar a auto-documentação do código.

O melhor argumento que vi para escrever "código de autodocumentação" é que ele evita o problema de comentários em texto livre que não concordam com o código como está escrito. A melhor crítica é que, embora o código possa descrever o que e como está fazendo por si só, não pode explicar por que algo está sendo feito de uma certa maneira.

O código de auto-documentação é um bom exemplo de "SECO" (não se repita). Não duplique as informações nos comentários que estão ou podem estar no próprio código.

Em vez de explicar para que uma variável é usada, renomeie a variável.

Em vez de explicar o que um pequeno trecho de código faz, extraia-o em um método e dê-lhe um nome descritivo (talvez uma versão abreviada do seu texto de comentário).

Em vez de explicar o que um teste complicado faz, extraia-o também para um método e dê-lhe um bom nome.

Etc.

Depois disso, você acaba com um código que não exige muita explicação, e ele se explica; portanto, você deve excluir os comentários que apenas repetem as informações no código.

Isso não significa que você não tenha nenhum comentário, há algumas informações que não podem ser inseridas no código, como informações sobre a intenção (o "porquê"). No caso ideal, o código e os comentários se complementam, cada um adicionando valor explicativo exclusivo sem duplicar as informações no outro.

o código de auto-documentação é uma boa prática e, se feito corretamente, pode transmitir facilmente o significado do código sem ler muitos comentários. especialmente em situações em que o domínio é bem compreendido por todos da equipe.

Dito isto, os comentários podem ser muito úteis para iniciantes ou testadores ou para gerar arquivos de documentação / ajuda.

o código de auto-documentação + os comentários necessários ajudarão as pessoas nas equipes.

Em ordem:

• Código de auto-documentação é um código que expressa claramente sua intenção para o leitor.
• Não inteiramente. Os comentários são sempre úteis para comentar o motivo pelo qual uma estratégia específica foi escolhida. No entanto, comentários que explicam o que uma seção de código está fazendo são indicativos de um código que não é suficientemente documentado e pode usar alguma refatoração.
• Os comentários ficam e ficam desatualizados. O código sempre diz é mais provável que diga a verdade.
• Eu nunca vi um caso em que o que do código não pudesse ser suficientemente claro sem comentários; no entanto, como eu disse anteriormente, às vezes é necessário / útil incluir comentários sobre o porquê .

É importante notar, no entanto, que o código realmente autodocumentado requer muita disciplina de auto e equipe. Você precisa aprender a programar de forma mais declarativa e precisa ser muito humilde e evitar códigos "inteligentes" em favor de códigos tão óbvios que parece que alguém poderia ter escrito.

Quando você lê um "código de auto-documentação", vê o que está fazendo, mas nem sempre consegue adivinhar por que está fazendo dessa maneira específica.

Existem inúmeras restrições que não são de programação, como lógica de negócios, segurança, demandas de usuários etc.

Quando você faz manutenção, essas informações em atraso se tornam muito importantes.

Apenas minha pitada de sal ...

Por um lado, considere o seguinte trecho:

/**
 * Sets the value of foobar.
 *
 * @foobar is the new vaue of foobar.
 */
 public void setFoobar(Object foobar) {
     this.foobar = foobar;
 }

Neste exemplo, você tem 5 linhas de comentários por 3 linhas de código. Pior ainda - os comentários não adicionam nada que você não possa ver lendo o código. Se você tiver 10 métodos como esse, poderá obter 'cegueira de comentários' e não perceber o único método que se desvia do padrão.

Obviamente, uma versão melhor teria sido:

/**
 * The serialization of the foobar object is used to synchronize the qux task.
 * The default value is unique instance, override if needed.
 */
 public void setFoobar(Object foobar) {
     this.foobar = foobar;
 }

Ainda assim, para código trivial, prefiro não ter comentários. A intenção e a organização geral são melhor explicadas em um documento separado fora do código.

A diferença está entre "o quê" e "como".

• Você deve documentar "o que" uma rotina faz.
• Você não deve documentar "como" ele faz isso, a menos que casos especiais (por exemplo, consulte um artigo específico sobre algoritmos). Isso deve ser auto-documentado.

Uma coisa que você pode apontar para o seu colega é que, independentemente de como o código dele seja auto-documentado, se outras abordagens alternativas forem consideradas e descartadas, as informações serão perdidas, a menos que ele comente o código com essas informações. Às vezes, é tão importante saber que uma alternativa foi considerada e por que foi decidida e os comentários de código provavelmente sobreviverão ao longo do tempo.

Em uma empresa em que trabalhei, um dos programadores colocou o seguinte na parte superior do monitor.

"Documente seu código como a pessoa que o mantém é um maníaco homocida que sabe onde você mora."

o código de auto-documentação normalmente usa nomes de variáveis ​​que correspondem exatamente ao que o código está fazendo, para que seja fácil entender o que está acontecendo

No entanto, esse "código de auto-documentação" nunca substituirá os comentários. Às vezes, o código é muito complexo e o código de auto-documentação não é suficiente, especialmente no que diz respeito à manutenção.

Certa vez, tive um professor que acreditava firmemente nessa teoria. De fato, a melhor coisa que já me lembro dele dizendo é: "Comentários são para mariquinhas". Pegamos
todos nós de surpresa a princípio, mas faz sentido.
No entanto, a situação é que, embora você possa entender o que está acontecendo no código, mas alguém com menos experiência, você pode ficar atrás de você e não entender o que está acontecendo. É quando os comentários se tornam importantes. Sei muitas vezes que não acreditamos que sejam importantes, mas há muito poucos casos em que comentários são desnecessários.

Estou surpreso que ninguém tenha trazido " Literate Programming ", uma técnica desenvolvida em 1981 por Donald E. Knuth da TeX e "The Art of Computer Programming".

A premissa é simples: como o código precisa ser entendido por um humano e os comentários são simplesmente descartados pelo compilador, por que não dar a todos o que eles precisam - uma descrição textual completa da intenção do código, sem restrições pelos requisitos da linguagem de programação , para o leitor humano e código puro para o compilador.

As ferramentas de programação alfabética fazem isso, fornecendo uma marcação especial para um documento que informa às ferramentas qual parte deve ser a origem e o que é o texto. O programa posteriormente retira as partes do código fonte do documento e monta um arquivo de código.

Encontrei um exemplo na Web: http://moonflare.com/code/select/select.nw ou a versão HTML http://moonflare.com/code/select/select.html

Se você encontrar o livro de Knuth em uma biblioteca (Donald E. Knuth, Literate Programming, Stanford, Califórnia: Centro de Estudos de Linguagem e Informação, 1992, CSLI Lecture Notes, nº 27.), você deve lê-lo.

Esse é o código de auto-documentação, completo com raciocínio e tudo. Até faz um bom documento, Tudo o resto é apenas comentários bem escritos :-)

Eu gostaria de oferecer mais uma perspectiva para as muitas respostas válidas:

O que é código fonte? O que é uma linguagem de programação?

As máquinas não precisam de código fonte. Eles estão felizes executando a montagem. Linguagens de programação são para nosso benefício. Não queremos escrever montagem. Precisamos entender o que estamos escrevendo. Programar é escrever código.

Você deve ler o que escreve?

O código-fonte não está escrito em linguagem humana. Foi tentado (por exemplo, FORTRAN), mas não foi completamente bem-sucedido.

O código-fonte não pode ter ambiguidade. É por isso que temos de colocar mais estrutura nele do que fazemos com o texto. O texto funciona apenas com o contexto, que tomamos como garantido quando usamos o texto. O contexto no código fonte é sempre explisit. Pense "usando" em c #.

A maioria das linguagens de programação possui redundância para que o compilador possa nos pegar quando não somos coerentes. Outros idiomas usam mais inferência e tentam eliminar essa redundância.

Nomes de tipo, nomes de métodos e nomes de variáveis ​​não são necessários pelos computadores. Eles são usados ​​por nós para referência. O compilador não entende a semântica, é para nós usarmos.

Linguagens de programação são uma ponte linguística entre homem e máquina. Tem que ser gravável para nós e legível para eles. As demandas secundárias são que elas sejam legíveis para nós. Se somos bons em semântica onde permitido e bons em estruturar o código, o código fonte deve ser fácil de ler, mesmo para nós. O melhor código não precisa de comentários.

Mas a complexidade espreita em todos os projetos, você sempre precisa decidir onde colocar a complexidade e quais camelos engolir. Esses são os lugares para usar comentários.

O código de auto-documentação é uma opção fácil para sair do problema, que, com o tempo, o código, os comentários e a documentação divergem. E é um fator disciplinar escrever código claro (se você é tão rigoroso consigo mesmo).

Para mim, estas são as regras que tento seguir:

• O código deve ser o mais fácil e claro de ler possível.
• Os comentários devem fornecer motivos para as decisões de design que eu tomei, como: por que eu uso esse algoritmo ou limitações que o código possui, como: não funciona quando ... (isso deve ser tratado em um contrato / afirmação no código) (geralmente dentro da função / procedimento).
• A documentação deve listar o uso (conversões de chamada), efeitos colaterais, possíveis valores de retorno. Pode ser extraído do código usando ferramentas como jDoc ou xmlDoc. Portanto, geralmente está fora da função / procedimento, mas próximo ao código que descreve.

Isso significa que todos os três meios de documentação do código estão próximos e, portanto, têm mais probabilidade de serem alterados quando o código é alterado, mas não se sobrepõem ao que expressam.

O verdadeiro problema com o chamado código de auto-documentação é que ele transmite o que realmente faz. Embora alguns comentários possam ajudar alguém a entender melhor o código (por exemplo, etapas de algoritmos, etc.), ele é redundante e duvido que você convença seu colega.

No entanto, o que é realmente importante na documentação é o material que não é diretamente evidente no código: intenção subjacente, suposições, impactos, limitações, etc.

Ser capaz de determinar que um código X faz uma rápida olhada é muito mais fácil do que determinar que um código não faz Y. Ele precisa documentar Y ...

Você pode mostrar a ele um exemplo de código que parece bem, é óbvio, mas na verdade não cobre todas as bases da entrada, por exemplo, e vê se ele o encontra.

Eu acho que o código de auto-documentação é um bom substituto para comentar. Se você precisar de comentários para explicar como ou por que o código é como é, então você tem nomes de funções ou variáveis ​​que devem ser modificados para serem mais explicativos. No entanto, o codificador pode decidir se ele vai compensar o déficit com um comentário ou renomear algumas variáveis ​​e funções e refatorar o código.

No entanto, ele não pode substituir sua documentação, porque documentação é o que você fornece a outras pessoas para explicar como usar seu sistema, e não como ele faz as coisas.

Edit: Eu (e provavelmente todos os outros) provavelmente devem ter a condição de que um aplicativo de Processamento de sinal digital (DSP) seja muito bem comentado. Isso ocorre principalmente porque os aplicativos DSP são essencialmente 2 para loops alimentados com matrizes de valores e adiciona / multiplica / etc valores mencionados ... para alterar o programa, você altera os valores em uma das matrizes ... precisa de alguns comentários para dizer o que você está fazendo nesse caso;)

Ao escrever código matemático, às vezes achei útil escrever comentários longos, como ensaios, explicando a matemática, as convenções notacionais que o código usa e como tudo se encaixa. Estamos falando de centenas de linhas de documentação aqui.

Tento tornar meu código o mais documentado possível, mas, quando volto a trabalhar nele depois de alguns meses, realmente preciso ler a explicação para não fazer dele um hash.

Agora, é claro que esse tipo de medida extrema não é necessária na maioria dos casos. Eu acho que a moral da história é: código diferente requer quantidades diferentes de documentação. Algum código pode ser escrito com tanta clareza que não precisa de comentários - então escreva com clareza e não use comentários lá!

Mas muito código precisa de comentários para fazer sentido; portanto, escreva-o da forma mais clara possível e, em seguida, use quantos comentários forem necessários ...

Eu diria - como muitos de vocês - que, para ser realmente auto-documentado, o código precisa mostrar alguma forma de intenção. Mas estou surpreso que ninguém tenha mencionado ainda o BDD - Behavior Driven Development . Parte da idéia é que você tem testes automatizados (código) explicando a intenção do seu código, o que é tão difícil de tornar óbvio de outra maneira.

Boa modelagem de domínio 
+ bons nomes (variáveis, métodos, classes) 
+ exemplos de código (testes de unidade de casos de uso) 
= software de auto-documentação 

Algumas razões pelas quais comentários adicionais além do código podem ser mais claros:

• O código que você está vendo foi gerado automaticamente e, portanto, qualquer edição no código pode ser prejudicada na próxima vez que o projeto for compilado
• Uma implementação não-simples foi trocada por um ganho de desempenho (desenrolando um loop, criando uma tabela de pesquisa para um cálculo caro etc.)

Será tudo o que a equipe valoriza em sua documentação. Eu sugeriria que documentar por que / intenção em vez de como é importante e isso nem sempre é capturado no código de auto-documentação. get / set no estes são óbvios - mas cálculo, recuperação etc algo do porquê deve ser expresso.

Também esteja ciente da diferença em sua equipe, se você for de nacionalidades diferentes. Diferenças na dicção podem criar nomes de métodos:

BisectionSearch

BinarySearch

BinaryChop

Esses três métodos contribuídos por desenvolvedores treinados em 3 continentes diferentes fazem a mesma coisa. Somente lendo os comentários que descrevem o algoritmo, conseguimos identificar a duplicação em nossa biblioteca.

Para mim, ler código que precisa de comentários é como ler texto no idioma que eu não conheço. Vejo afirmações e não entendo o que faz ou por quê - e tenho que olhar para os comentários. Li uma frase e preciso procurar no dicionário para entender o que isso significa.

Geralmente é fácil escrever código que auto-documenta o que faz. Para dizer o porquê, os comentários são mais adequados, mas mesmo aqui o código pode ser melhor. Se você entende seu sistema em todos os níveis de abstração, tente organizar seu código como

public Result whatYouWantToDo(){
  howYouDoItStep1();
  howYouDoItStep2();
  return resultOfWhatYouHavDone;
}

Onde o nome do método reflete sua intenção e o corpo do método explica como você alcança seu objetivo. De qualquer forma, você não pode contar o livro inteiro em seu título, portanto, as principais abstrações do seu sistema ainda precisam ser documentadas, bem como algoritmos complexos, contratos de método não triviais e artefatos.

Se o código que o seu colega produz é realmente auto-documentado, você e ele têm sorte. Se você acha que o código de seus colegas precisa de comentários, ele precisa. Basta abrir o lugar mais trivial, ler uma vez e ver se você entendeu tudo ou não. Se o código é auto-documentado - você deve. Caso contrário - faça uma pergunta ao colega, depois que ele lhe der uma resposta, pergunte por que essa resposta não foi documentada nos comentários ou no código anteriormente. Ele pode alegar que o código é auto-documentado para uma pessoa inteligente como ele, mas de qualquer maneira precisa respeitar outros membros da equipe - se suas tarefas exigirem a compreensão do código dele e o código dele não explicar tudo o que você precisa entender - ele precisa comentários.

A maioria da documentação / comentários serve para auxiliar futuros desenvolvedores / aprimoradores de código, tornando o código sustentável. Frequentemente, acabávamos voltando ao nosso módulo posteriormente para adicionar novos recursos ou otimizar. Naquele momento, seria mais fácil entender o código simplesmente lendo os comentários do que passar por vários pontos de interrupção. Além disso, prefiro gastar tempo pensando em uma nova lógica do que decifrar a existente.

Acho que o que ele pode estar dizendo é que, se os comentários explicam o que o código está fazendo, ele deve ser reescrito para ficar claro qual é a sua intenção. É isso que ele quer dizer com código de auto-documentação. Geralmente, isso pode significar simplesmente dividir a função longa em partes menores lógicas com um nome descritivo da função.

Isso não significa que o código não deve ser comentado. Isso significa que os comentários devem fornecer uma razão pela qual o código está escrito da maneira que está.

Acredito que você deve sempre se esforçar para obter código de auto-documentação, pois facilita a leitura do código. No entanto, você também precisa ser pragmático sobre as coisas.

Por exemplo, geralmente adiciono um comentário a todos os alunos (uso comentários da documentação para isso). Isso descreve o que o membro deve fazer, mas não como o faz. Descobri que quando estou lendo o código, particularmente o antigo, isso me ajuda a lembrar rapidamente para que serve o membro e também acho mais fácil do que ler o código e resolvê-lo, principalmente se o fluxo do código saltar um pouco .

Esta é só minha opinião. Conheço muitas pessoas que trabalham sem comentários e digo que acham que isso não é problema. No entanto, perguntei a alguém sobre um método que escreveram seis meses antes e eles tiveram que pensar por alguns minutos para me dizer exatamente o que ele fez. Isso não é um problema se o método for comentado.

Finalmente, você deve se lembrar que os comentários são igualmente parte do sistema como código. Ao refatorar e alterar a funcionalidade, você também deve atualizar seus comentários. Esse é um argumento contra o uso de comentários, pois eles são piores que inúteis se estiverem incorretos.