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

258

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.

Adam Davis
fonte
118
Você sabe o que realmente me impressiona? Você discorda do cara, mas está pedindo para entendê-lo, não por mais munição contra ele.
kajaco
14
Como uma história de um caso extremamente oposto, tenho uma colega de trabalho que escreve toneladas de documentação: em cada arquivo cpp, ela inclui um manual com pelo menos algumas dúzias de páginas sobre a implementação e o uso das funções fornecidas. No entanto, ela escreve funções desastrosamente longas e complicadas (funções únicas com 8000 linhas de código), identificadores contra-intuitivos para variáveis ​​e funções, etc. comenta qualquer dia, desde que seu código seja bem organizado, com pequenas funções fáceis de entender.
stinky472
Relacionados: thedailywtf.com/Articles/...
Calmarius
1
Em resumo, pode-se evitar a maioria dos comentários que explicam como o código funciona e faz com que o código se auto-documente nesse sentido. Mas muitas vezes também é necessário explicar por que o código funciona da maneira que funciona, por exemplo, quando você trabalha em torno de uma limitação em uma biblioteca. Você geralmente precisa de comentários para explicar o porquê.
Lutz Prechelt
2
Eu costumava trabalhar com alguém que comentava demais tudo, mas geralmente com comentários inúteis, como i++; // increment i- mas sem nenhuma explicação sobre por que i deveria ser incrementado nesse ponto da função.
Nnnnnn

Respostas:

177

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.

OregonGhost
fonte
Em linha com esta resposta, eu penso: memeagora.blogspot.com/2008/11/comments-code-smell.html
Maslow
14
Ponto n. 3 deve fazer parte do ponto n. 1 IMHO, se um método é tão complexo que requer comentários de alta abstração para vários blocos de código, cada um desses blocos de código deve ser um novo método.
Bjarke Freund-Hansen
10
+1 em "não significa que não haja comentários", o que parece ser a opinião de algumas pessoas.
Skurmedel
4
Ainda não é necessário comentar que: public static Collection <File> filesGreatsThan (caminho do arquivo, int sizeInBytes);
Trylks
6
Uma boa regra para mim é que os comentários nunca devem explicar o que o código está fazendo, mas podem ser usados ​​para explicar por que estão fazendo isso. Em outras palavras, comente um bloco de código para explicar por que ele está lá, não como ele funciona. Se você pode fatorar o bloco em seu próprio método claramente nomeado, isso é ainda melhor. É disso que se trata o código de auto-documentação.
Mel
387

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.

ine
fonte
73
Todo esse pedaço deve realmente estar em uma função com um nome descritivo embora;)
workmad3
7
Sim, a função displacementDueToGravity (int timeInSeconds, float gravitationalAcceleration = 9.81) seria mais fácil para eu ler.
Cristián Romo
18
O único comentário que sinto falta aqui é: Por que 5 segundos?
John Nilsson
3
Outro voto para o nome da função descritiva. Não fornece a equação em si, mas não vejo que isso seja necessário.
Loren Pechtel 16/10/08
18
Quais são as unidades de força gravitacional? Existem limites para o quanto você pode adicionar a um nome de variável. Em algum momento você precisa explicar o que está tentando fazer . Geralmente isso não é óbvio , e é por isso que você precisa comentar o código. É besteira dizer que o código é auto-documentado, é apenas auto- descritivo .
776 Nick
172

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!

andygeers
fonte
Acordado. Embora, ocasionalmente, até o melhor código possa ocultar qual é o seu efeito final, isso é tratado respondendo o porquê nos comentários. Como em "Por que você acabou de alterar essas 5 variáveis ​​dessa maneira?"
Sam Erwin
My 2 Cent: o caso [Unit, Spec, Behavior,] não é uma resposta para "por que diabos"? Então você pode ler o caso de teste e deve ter a intenção de explicar o porquê.
21416 Jonke
2
Acho que eles podem responder ao porquê de alto nível, mas não explicam coisas como "Estou preenchendo essa estrutura com tantos bytes, para que ela permaneça adequadamente alinhada quando transmitida a alguma plataforma obscura". Para esses, os comentários de código são a melhor maneira de preservar o conhecimento institucional.
tsellon 16/10/08
E, portanto, você deve comentar onde a intenção não é inequívoca, dado o próprio código.
Draemon 17/10/08
2
@tsellon, sua especificação automatizada pode lhe dizer isso, e o bom é o código que verifica o código de implementação. Portanto, se a implementação mudar de alguma forma, a especificação será interrompida. Quão legal é isso? Comentários que alertam quando o código de implementação não está mais fazendo o que o comentário especificou?
Pragmatic Agilist 04/09/09
96

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.

Loofer
fonte
28
O que parece trivial para você entender no momento da escrita do código pode, de fato, ser muito difícil para outra pessoa entender mais tarde, mesmo que essa pessoa seja de fato você mesmo em alguns meses / anos.
Anders Sandvig
15
Costumo encontrar coisas que eu escrevi na sexta-feira muito difícil de Grokar na segunda-feira de manhã :)
Loofer
1
que nos leva a "tente não escrever comentários"
mustafabar
37

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 .

Scott Dorman
fonte
1
IMHO O bloco deve informar como , o nome da função deve informar o porquê . Contanto que você use os dois juntos, você transmite a intenção e a implementação .... int GetBoundingBox() {return CalcContentDimensions() + this.padding + this.margin;}... #
Basic
19

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.

Mike Burton
fonte
2
você precisa de mais votos positivos, seu exemplo explica por que devemos usar nomes de função para documentar a intenção.
Ape-inago 19/01
16

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.

EBGreen
fonte
26
Lixo. Bons comentários no código têm absolutamente o seu lugar. Pegue o exemplo da escolha entre dois métodos igualmente corretos para resolver um problema. Um comentário explicando por que um método foi escolhido sobre o outro é extremamente significativo e você nunca pode obtê-lo no próprio código.
22432 Scott Dorman
7
Se existem dois métodos IGUALMENTE CORRETOS, então importa por que você escolheu um sobre o outro?
EBGreen
1
Sim, igualmente correto não significa exatamente o mesmo. Um método pode ser mais rápido em algumas situações que outro.
Ikke
Então, se o seu critério de decisão for a velocidade, eles não serão IGUALMENTE CORRETOS. Não estou dizendo que os comentários são ruins. Só que eles são necessários porque atualmente não existe uma linguagem de programação tão clara e inequívoca que qualquer pessoa possa olhar o código e saber instantaneamente a intenção do código.
EBGreen
9
Não acho que as pessoas entendam essa citação da mesma maneira que eu. Entendo que você deve sempre escrever um código tão claro que não precise ser comentado, mas que você deve aceitar que é um ideal que nunca funciona na realidade.
#
14

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.

Steven Huwig
fonte
14

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.

Cunha
fonte
4
Uma exceção: programadores ruins. Vi comentários dizerem que o código está fazendo algo que não está. Então eu me pergunto: devo corrigir o código ou o comentário?
Guge
Você não pode vencer os nomes dos métodos no Objective-C. :)
13

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.

Gulzar Nazim
fonte
9

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.

Avdi
fonte
Vou adicionar um nit pick aqui. Código nem sempre "diz a verdade". O código pode ser enganoso e ofuscar suas intenções com muita facilidade. Por exemplo, uma variável ou método com nome errado pode estar tanto quanto um comentário desatualizado.
04:
Os nomes dos métodos podem mentir e também podem estar desatualizados.
Calmarius
7

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 ...

ulm
fonte
6

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.

ddimitrov
fonte
Pode parecer trivial documentar getters e setters, mas acho que existe um meio feliz entre ter um comentário inútil e não ter nenhum comentário. O objetivo de muitos comentários do Javadoc é informar alguém que não pode ou não tem a tendência de examinar o código no método.
James McMahon
6

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.
Stefano Borini
fonte
Discordo fortemente. O que uma rotina faz deve ser óbvio pelo nome. Como isso acontece deve ser óbvio a partir do código de implementação. Por que a implementação foi escrita como está deve ser documentada .
Anthony Manning-Franklin
5

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.

Onorio Catenacci
fonte
Você toma isso como uma regra e acabará escrevendo um livro na sua base de código ;-) Eu concordo com decisões não óbvias.
Ddimitrov 16/10/08
@dditritrov, é uma boa observação. Mas, como você diz para decisões não óbvias (e geralmente são as que realmente exigem documentação), é uma boa prática.
Onorio Catenacci
Documente o código que não foi escrito! :)
Tony
5

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."

JoeOD
fonte
4

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.

Josh Mein
fonte
Depois refatorar até ficar mais claro. Acredito firmemente que não há nada que não possa ser dito claramente por código.
Tigraine 16/10/08
4
Exceto por que uma implementação, algoritmo ou fórmula específica foi escolhida em detrimento de outra igualmente correta. Você nunca pode descrever por que uma escolha foi feita no código, apenas o que foi essa escolha.
22426 Scott Dorman
1
@ Scott: você pode colocar as duas opções em uma classe maior e deixar a outra não implementada com um comentário sobre ... oh, espere.
Ape-inago 19/01/12
4

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 :-)

Quantenmechaniker
fonte
Na verdade, isso é o oposto do código de auto-documentação. Texto para o humano, código para a máquina. E qual idioma deve ser o código? Assembléia, é claro. Os humanos não precisam ler, certo? Eles só precisam escrever!
Guge
4

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.

Guge
fonte
3

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.

Ralph M. Rickenbach
fonte
3

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.

Uri
fonte
3

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;)

workmad3
fonte
Portanto, um nome de função ou variável fornecerá um contexto trivialmente claro o suficiente para explicar por que uma implementação foi escolhida em detrimento de outra, dada duas ou mais maneiras igualmente corretas de resolver um problema?
Scott Dorman
3

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 ...

tempestade
fonte
3

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 
Torbjørn
fonte
2

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.)
John
fonte
2

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.

MikeJ
fonte
2

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.

Pavel Feldman
fonte
2

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.

sy
fonte
1

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á.

Korbin
fonte
1

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.

BlackWasp
fonte