O que é código de autodocumentação e pode replace o código bem documentado?

Eu tenho um colega que insiste que seu código não precisa de comentários, é “auto-documentado”.

Revisei seu código e, embora seja mais claro do que o código que vi outros produzirem, ainda discordo de que o código de autodocumentação é tão completo e útil quanto o código comentado e documentado.

Me ajude a entender seu ponto de vista.

  • O que é código de auto-documentação
  • Pode realmente replace o código bem comentado e documentado
  • Existem situações em que é melhor 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 seja 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 apresente razões pelas quais o código bem comentado e documentado é de alta prioridade – há muitos resources mostrando isso, mas eles não são convincentes para o meu colega. Acredito que preciso entender mais completamente sua perspectiva para convencê-lo do contrário. Comece uma nova pergunta se precisar, mas não discuta aqui.

Nossa resposta rápida! Por favor, leia todas as respostas existentes e forneça comentários às respostas em vez de adicionar novas respostas, a menos que sua resposta seja substancialmente diferente de todas as outras respostas 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ódigos auto-documentados. Espero que os outros votem em você se você não ficar no assunto.

Na minha opinião, qualquer código deve ser auto-documentado. Em um bom código auto-documentado, você não precisa explicar cada linha porque cada identificador (variável, método, class) tem um nome semântico claro. Ter mais comentários do que o necessário, na verdade, torna mais difícil (!) Ler o código, por isso, se o seu colega

  • escreve comentários de documentação (Doxygen, JavaDoc, comentários XML, etc.) para cada class, membro, tipo e método E
  • claramente comenta quaisquer partes do código que não sejam auto-documentadas 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 maior (ou seja, localizar todos os arquivos maiores que 10 MB em vez de percorrer todos os arquivos em um diretório, testar se o tamanho do arquivo for maior que 10 MB, retorno de rendimento se verdadeiro )

seu código e documentação 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. No entanto, a questão é que, ao ler o código (incluindo comentários e comentários de documentação), deve-se obter uma compreensão imediata do que o código faz e por quê. Se o código de “auto-documentação” demorar mais para entender do que o código comentado, ele não é realmente auto-documentado.

Bem, já que isso é sobre comentários e código, vamos ver um 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 então para este código documentado, o que explica melhor porque 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, comentários são usados ​​quando variables ​​deveriam ter sido nomeadas descritivamente, e os resultados de uma operação são resumidos quando podemos ver claramente qual é a operação. Eu preferiria o segundo exemplo auto-documentado a este qualquer dia, e talvez seja isso que seu amigo está falando quando ele 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 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 importante dos comentários. Se estiver escrito corretamente, já sabemos o que o código faz, só precisamos saber por que ele faz isso!

Alguém disse uma vez

1) Apenas escreva comentários para códigos difíceis de entender.
2) Tente não escrever código que seja difícil de entender.

A idéia por trás do código “auto-documentado” é que a lógica real do programa no código é trivialmente clara o suficiente para explicar a qualquer um que ler o código não apenas o que o código está fazendo, mas por que está fazendo isso.

Na minha opinião, a ideia do verdadeiro código de autodocumentação é um mito. O código pode dizer a lógica por trás do que está acontecendo, mas não pode explicar por que isso está sendo feito de uma determinada maneira, especialmente se houver mais de uma maneira de resolver um problema. Por essa razão, nunca pode replace o código bem comentado .

Eu acho que é relevante questionar se uma linha particular de código é auto-documentada, mas no final, se você não entender a estrutura e a function de uma fatia de código, a maioria dos comentários de tempo não ajudará. Tomemos, por exemplo, a fatia do código “corretamente comentado” do 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); 

Este código é bom, mas o seguinte é igualmente informativo na maioria dos sistemas de software modernos, e reconhece explicitamente que usar um cálculo newtoniano é uma escolha que pode ser alterada caso algum 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, há pouquíssimas situações de codificação “normais”, nas quais você precisa de comentários. Com que frequência você acaba rolando seu próprio algoritmo, por exemplo? Basicamente tudo o mais é uma questão de estruturar seu sistema de modo que um codificador possa compreender as estruturas em uso e as escolhas que levaram o sistema a usar essas estruturas específicas.

Eu esqueci de onde eu tirei isso, mas:

Todo comentário em um programa é como uma desculpa para o leitor. “Sinto muito que meu código seja tão obscuro que você não possa entendê-lo olhando para ele”. Nós apenas temos que aceitar que não somos perfeitos, mas nos esforçamos para ser perfeitos e pedir desculpas quando precisamos.

O código de auto-documentação é um bom exemplo de “DRY” (Don’t Repeat Yourself). Não duplique informações nos comentários, o que é, ou pode ser, 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 snippet curto de código faz, extraia-o em um método e dê a ele um nome descritivo (talvez uma versão abreviada do seu texto de comentário).

Em vez de explicar o que é um teste complicado, extraia isso em um método e dê um bom nome.

Etc.

Depois disso, você acaba com um código que não exige tanta explicação, ele explica a si mesmo, portanto, você deve excluir os comentários que meramente repetem informações no código.

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

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

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

O código de autodocumentação + os comentários necessários ajudarão muito as pessoas das equipes.

Primeiro de tudo, é bom saber que o código do seu colega é mais claro do que o outro código que você viu. Isso significa que ele provavelmente não está usando “autodocumentação” como desculpa para ficar com preguiça de comentar seu código.

O código de autodocumentação é um código que não requer comentários em texto livre para que um leitor informado entenda o que está fazendo. Por exemplo, esse trecho de código é autodocumentado:

 print "Hello, World!" 

e assim é isto:

 factorial n = product [1..n] 

e assim é isto:

 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 ideia de um “leitor informado” é muito subjetiva e situacional. Se você ou qualquer outra pessoa está tendo problemas para seguir o código do seu colega, então ele faria bem em reavaliar sua idéia de um leitor informado. Algum nível de familiaridade com o idioma e as bibliotecas que estão sendo usados ​​deve ser assumido para chamar a auto-documentação do código.

O melhor argumento que tenho visto para escrever “código de auto-documentação” é que 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 ele está fazendo por si só, ele não pode explicar por que algo está sendo feito de uma determinada maneira.

Em ordem:

  • O código de autodocumentaçã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 determinada estratégia foi escolhida. No entanto, os comentários que explicam o que uma seção de código está fazendo são indicativos de código que é insuficientemente auto-documentado e poderia usar alguma refatoração.
  • Comentários mentem e ficam desatualizados. Código sempre diz que é mais provável dizer a verdade.
  • Eu nunca vi um caso em que o código do código não pudesse ser suficientemente claro sem comentários; entretanto, como eu disse anteriormente, às vezes é necessário / útil include comentários sobre o porquê .

É importante notar, no entanto, que o código realmente auto-documentado exige muita disciplina pessoal e de equipe. Você tem que aprender a programar mais declarativamente, e você tem que ser muito humilde e evitar código “inteligente” em favor de código que é tão óbvio que parece que alguém poderia ter escrito.

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. Ainda pior – os comentários não adicionam nada que você não pode ver lendo o código. Se você tem 10 methods como esse, você pode obter ‘cegueira de comentários’ e não perceber o único método que se desvia do padrão.

Se claro, 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.

Quando você lê um “código de autodocumentação”, vê o que está fazendo, mas nem sempre consegue adivinhar por que ele está sendo feito dessa maneira específica.

Existem toneladas de restrições de não programação, como lógica de negócios, segurança, demandas do usuário, etc.

Quando você faz manutenção, essas informações de fundo tornam-se muito importantes.

Apenas minha pitada de sal …

Uma coisa que você gostaria de chamar a atenção do colega é que, independentemente de quão autodocumentado é o seu código, se outras abordagens alternativas forem consideradas e descartadas, a informação será perdida, a menos que ele comente o código com essa informação. À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.

Você já ouviu falar do projeto “WEB” de Donald Knuth para implementar seu conceito de Programação Literada ? É mais do que código auto-documentado; é mais como uma documentação que pode ser compilada e executada como código. Eu não sei o quanto é usado hoje embora.

A diferença é entre “o que” e “como”.

  • Você deve documentar “o que” uma rotina faz.
  • Você não deve documentar “como” faz isso, a menos que casos especiais (por exemplo, referir-se a um papel de algoritmo específico). Isso deve ser auto documentado.

Em uma empresa onde trabalhei, um dos programadores tinha o seguinte preso ao topo de seu monitor.

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

O ponto de vista de que o código é auto-documentável me deixa louco. Uma linha particular de código ou um sub-algoritmo pode ser, na verdade, auto-documentável, mas seu propósito, na maior parte, simplesmente não é.

Fiquei tão frustrado com isso há um mês ou dois atrás que escrevi um post inteiro descrevendo meu ponto de vista. Poste aqui .

O código de auto-documentação normalmente usa nomes de variables ​​que correspondem exatamente ao que o código está fazendo, de forma que é fácil entender o que está acontecendo

No entanto, esse “código de auto-documentação” nunca replaceá 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. Na verdade, a melhor coisa que eu sempre lembro dele dizendo é: “Comentários são para maricas”.
Levou todos nós de surpresa no começo, mas faz sentido.
No entanto, a situação é que mesmo que você seja capaz de entender o que está acontecendo no código, mas alguém com menos experiência você pode vir atrás de você e não entender o que está acontecendo. É quando os comentários se tornam importantes. Eu sei muitas vezes que não acreditamos que sejam importantes, mas há poucos casos em que comentários são desnecessários.

Estou surpreso que ninguém tenha trazido ” Programação Literada “, uma técnica desenvolvida em 1981 por Donald E. Knuth, do TeX, e “The Art of Computer Programming”.

A premissa é simples: como o código deve ser entendido por um ser 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 por requisitos de linguagem de programação. , para o leitor humano e código puro para o compilador.

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

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

Se você puder encontrar o livro de Knuth sobre isso em uma biblioteca (Donald E. Knuth, Programação Literária, Stanford, Califórnia: Centro para o Estudo da Linguagem e Informação, 1992, CSLI Lecture Notes, no. 27), você deve lê-lo.

Isso é código de auto-documentação, completo com raciocínio e tudo. Até faz um bom documento, Tudo mais é apenas um comentário bem escrito 🙂

Minha opinião está escrita neste post:

A única dica para documentar seu código.

Excerto:

Em vez de escrever muitos comentários para explicar os comportamentos sutis do seu programa, por que não reestruturar suas lógicas para que sejam auto-evidentes? Em vez de documentar o que um método está fazendo, por que não escolher um nome claro para esse método? Em vez de marcar seu código para indicar trabalho inacabado, por que não apenas lançar um NotImplementedException ()? Em vez de se preocupar se seus comentários soam educados o suficiente para o seu chefe, seus colegas ou qualquer um que esteja lendo o código, por que não parar de se preocupar em não escrevê-los?

Quanto mais claro for o seu código, mais fácil será mantê-lo, estendê-lo, trabalhá-lo em futuras edições. Quanto menos ordez for o seu código, menor será a necessidade de comentá-lo. Quanto mais os comentários, maior o custo de manutenção.

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 correndo assembly. Linguagens de programação são para nosso benefício. Nós não queremos escrever assembly. Precisamos entender o que estamos escrevendo. Programação é sobre escrever código.

Você deve ser capaz de ler o que você escreve?

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

O código-fonte não pode ter ambigüidade. É por isso que temos que colocar mais estrutura nisso do que com texto. O texto só funciona com o contexto, o que tomamos por certo quando usamos o texto. Contexto no código-fonte é sempre explisit. Pense “usando” em c #.

A maioria das linguagens de programação tem redundância, de modo que o compilador pode nos pegar quando não somos coerentes. Outras linguagens usam mais inferência e tentam eliminar essa redundância.

Nomes de tipos, nomes de methods e nomes de variables ​​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, isso é para nós usarmos.

Linguagens de programação são uma ponte lingüística entre homem e máquina. Tem que ser gravável para nós e legível para eles. As exigências secundárias são de que seja legível para nós. Se somos bons em semântica, onde permitido e bom 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 tem que 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 de sair do problema, que com o código de tempo, comentário e documentação divergem. E é um fator disciplinador escrever código claro (se você é tão rígido consigo mesmo).

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

  • Código deve ser tão fácil e claro para ler quanto possível.
  • Comentários devem dar razões para decisões de design que eu tomei, como: por que eu uso esse algoritmo, ou limitações que o código tem, como: não funciona quando … (isso deve ser tratado em um contrato / asserção no código) (geralmente dentro da function / procedimento).
  • A documentação deve listar o uso (chamadas de conversões), 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 function / procedimento, mas próximo ao código que descreve.

Isso significa que os três meios de documentar o código residem juntos e, portanto, têm maior probabilidade de serem alterados quando o código é alterado, mas não se sobrepõem ao que eles expressam.

O problema real 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ê convencesse seus colegas.

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 faz o X de uma rápida olhada é muito mais fácil do que ser capaz de determinar que um código não faz Y. Ele tem que documentar Y …

Você poderia mostrar a ele um exemplo de um código que parece bem, é óbvio, mas na verdade não cobre todas as bases da input, por exemplo, e veja se ele a 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 é da maneira que é, então você tem uma function ou nomes de variables ​​que devem ser modificados para serem mais explicativos. Pode ser até o codificador se ele vai compensar o déficit com um comentário ou renomear algumas variables ​​e funções e refatorar o código.

Ele não pode realmente replace sua documentação, porque a documentação é o que você dá aos outros para explicar como usar seu sistema, ao invés de como ele faz as coisas.

Edit: Eu (e provavelmente todos os outros) provavelmente deve ter a disposição que um aplicativo de processamento de sinal digital (DSP) deve ser muito bem comentado. Isso é principalmente porque os aplicativos DSP são essencialmente 2 for loops alimentados com matrizes de valores e adiciona / multiplica / etc disse valores … para alterar o programa que você alterar os valores em um dos arrays … precisa de um par de comentários para dizer o que você está fazendo nesse caso;)

When writing mathematical code, I have sometimes found it useful to write long, essay-like comments, explaining the math, the notational conventions the code uses, and how it all fits together. We’re talking hundreds of lines of documentation, here.

I try to make my code as self-documenting as possible, but when I come back to work on it after a few months, I really do need to read the explanation to keep from making a hash out of it.

Now, of course this kind of extreme measure isn’t necessary for most cases. I think the moral of the story is: different code requires different amounts of documentation. Some code can be written so clearly that it doesn’t need comments — so write it that clearly and don’t use comments there!

But lots of code does need comments to make sense, so write it as clearly as possible and then use as many comments as it needs…

I would argue – as many of you do – that to be truly self documenting, code needs to show some form of intent. But I’m surprised nobody mentioned BDD yet – Behavior Driven Development . Part of the idea is that you have automated tests (code) explaining the intent of your code, which is so difficult to make obvious otherwise.

Good domain modeling 
+ good names (variabes, methods, classs) 
+ code examples (unit tests from use cases) 
= self documenting software 

A couple of reasons why extra comments in addition to the code might be clearer:

  • The code you’re looking at was generated automatically, and hence any edits to the code might be clobbered the next time the project is compiled
  • A less-than-straightforward implementation was traded off for a performance gain (unrolling a loop, creating a lookup table for an expensive calculation, etc.)

Its going to be all in what the team values in its documentation. I would suggest that documenting why/intent instead of how is important and this isn’t always captured in self documenting code. get/set no these are obvious – but calculation, retrieval etc something of the why should be expressed.

Also be aware of difference in your team if you are comming from different nationalities. Differences in diction can creap into the naming of methods:

BisectionSearch

BinarySearch

BinaryChop

These three methods contributed from developers trained on 3 different continents do the same thing. Only by reading the comments that described the algorithm were we able to identify the duplication in our library.

For me reading code that needs comments is like reading text in the language I do not know. I see statement and I do not understand what it does or why – and I have to look at comments. I read a phrase and I need to look in dictionary to understand what it means.

It is usually easy to write code that self-documents what it does. To tell you why it does so comments are more suitable, but even here code can be better. If you understand your system on every level of abstraction, you should try organizing you code like

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

Where method name reflects your intent and method body explains how you achieve your goal. You anyway can not tell entire book in its title, so main abstractions of your system still have to be documented, as well as complex algorithms, non-trivial method contracts and artifacts.

If the code that your colleague produc is really self-documented – lucky you and him. If you think that your colleagues code needs comments – it needs. Just open the most non-trivial place in it, read it once and see if you understood everything or not. If the code is self-documented – then you should. If not – ask your colleague a question about it, after he gives you an answer ask why that answer was not documented in comments or code beforehand. He can claim that code is self-document for such smart person as him, but he anyway has to respect other team members – if your tasks require understanding of his code and his code does not explain to you everything you need to understand – it needs comments.

    Intereting Posts