“Comentários são um cheiro de código” [fechado]

Um colega meu acredita que qualquer uso de comentários no código (ou seja, não método de estilo javadoc ou comentários de classe) é um cheiro de código . O que você acha?

Somente se o comentário descrever o que o código está fazendo.

Se eu quisesse saber o que estava acontecendo em um método ou bloco, leria o código. Espero, de qualquer maneira, que qualquer desenvolvedor que trabalhe em um determinado projeto esteja pelo menos familiarizado com a linguagem de desenvolvimento para ler o que está escrito e entender o que está fazendo.

Em alguns casos de otimização extrema, você pode estar usando técnicas que dificultam a alguém seguir o que seu código está fazendo. Nesses casos, os comentários podem e devem ser usados ​​para não apenas explicar por que você tem essas otimizações, mas o que o código está fazendo. Uma boa regra geral seria deixar alguém (ou várias outras pessoas) familiarizado com a linguagem e o projeto de implementação ver o seu código - se eles não conseguirem entender o porquê e o como, então você deve comentar o porquê e o como.

No entanto, o que não está claro no código é o motivo pelo qual você fez algo. Se você adotar uma abordagem que pode não ser óbvia para os outros, faça um comentário que explique por que você tomou as decisões que tomou. Eu suspeitaria que você nem percebesse que um comentário é necessário até depois de algo como uma revisão de código, onde as pessoas querem saber por que você fez X em vez de Y - você pode capturar sua resposta no código para todos os que o olham. no futuro.

O mais importante, no entanto, é alterar seus comentários quando você altera seu código. Se você alterar um algoritmo, certifique-se de atualizar os comentários com o motivo pelo qual você seguiu o algoritmo X sobre Y. Comentários obsoletos são um cheiro de código ainda maior.

Isso é particularmente irritante de ouvir no momento. Passei algum tempo neste fim de semana analisando códigos muito bem nomeados, limpos e não comentados, implementando um algoritmo de pesquisa (um que não é realmente publicado). Eu estou familiarizado com isso, o cara sentado ao meu lado foi o inventor e o código foi escrito há alguns anos por outra pessoa. Mal podíamos segui-lo.

Seu colega de trabalho não tem experiência suficiente, obviamente.

Os comentários devem explicar o porquê, não como.

Howos comentários do tipo geralmente são mais bem tratados com a refatoração. Pessoalmente, geralmente evito comentários a favor da refatoração.

Antes:

# convert to cents
a = x * 100

# avg cents per customer 
avg = a / n

# add to list
avgs < avg
t += 1

depois de:

total_cents = total * 100
average_per_customer = total_cents / customer_count

track_average(average_per_customer)

Eu declaro seu colega de trabalho um herege! Onde estão minhas botas queimando hereges?

Obsessivo comentando é ruim e uma dor de cabeça de manutenção, e os comentários são nenhum substituto para métodos bem-nomeados, classes, variáveis, etc. Mas às vezes colocando por isso que algo está do jeito que está pode ser extremamente valiosa para os pobres idiota que tem de manter o código em seis meses - principalmente quando aquele pobre idiota acaba sendo você.

Alguns comentários reais do código em que estou trabalhando:

    // If this happens, somebody's been screwing around with the database definitions and
    // has removed the restriction that a given alarm may have only one entry in the 
    // notifications table.  Bad maintenance programmer!  Bad!  No biscuit!



    // If an alert is active on our side but inactive on theirs, that might mean
    // they closed the alert.  (Or that we just haven't told them about it yet.)  The
    // logic comes later; for now, we'll just compile it in a list.



    // If we know for a fact that an alarm isn't getting through, we're going to whine pretty
    // aggressively about it until it gets fixed.

Idealmente, o código deve ser tão bem codificado que deve ser autoexplicativo. No mundo real, sabemos que às vezes também é necessário comentar um código de alta qualidade.

O que você absolutamente deve evitar é a "redundância de código de comentário" (comentários que não adicionam nada ao código):

i++; // Increment i by 1

Então, se houver um bom design de código (e mantido / alinhado) e documentação, comentar será ainda menos útil.

Mas, em algumas circunstâncias, os comentários podem ser uma boa ajuda na legibilidade do código:

while( foo )
{
     if( dummy )
     {
     }
     else // !dummy
     {
     }
} // end while( foo )

Não se esqueça que você deve manter e manter sincronizados os comentários ... comentários desatualizados ou errados podem ser uma dor terrível! E, como regra geral, comentar demais pode ser um sintoma de uma programação ruim.

Definir categoricamente um método ou processo como um "cheiro de código" é um "cheiro de fanatismo". O termo está se tornando o novo "considerado prejudicial".

Lembre-se de que todos esses tipos de coisas devem ser diretrizes.

Muitas das outras respostas dão bons conselhos sobre quando os comentários são justificados.

Pessoalmente, uso muito poucos comentários. Explique o propósito de processos não óbvios e deixe a ameaça de morte ocasional para qualquer um que possa estar pensando em alterar as coisas por conta própria que exigiram semanas de ajuste.

Refatorar tudo até que um aluno do jardim de infância possa entender que provavelmente não é um uso eficiente do seu tempo e provavelmente não terá um desempenho tão bom quanto uma versão mais concisa.

Os comentários não afetam o tempo de execução, portanto, o único problema negativo a ser considerado é a manutenção.

Em alguns casos, nenhuma boa nomeação, refatoração etc. pode substituir um comentário. Veja este exemplo do mundo real (o idioma é Groovy):

  response.contentType="text/html"
  render '{"success":true}'

Parece estranho, não é? Provavelmente um erro de copiar e colar? Chora por uma correção de bug?

Agora o mesmo com os comentários:

  // DO NOT TOUCH THE FOLLOWING TWO LINES; the ExtJS UploadForm requires it exactly like that!!!
  response.contentType="text/html"  // must be text/html so the browser renders the response within the invisible iframe, where ExtJS can access it
  render '{"success":true}'         // ExtJS expects that, otherwise it will call the failure handler instead of the succss handler

A questão principal aqui é o significado do termo "cheiro de código".

Muitas pessoas (incluindo você, eu acho) entendem que o cheiro do código é algo próximo a um erro ou pelo menos algo que precisa ser corrigido. Talvez você pense nisso como um sinônimo de "antipadrão".

Este não é o significado do termo!

A metáfora do cheiro do código é originária do Wards Wiki e enfatizam:

Observe que um CodeSmell é uma dica de que algo pode estar errado, não uma certeza. Um idioma perfeitamente bom pode ser considerado um CodeSmell porque geralmente é mal utilizado ou porque existe uma alternativa mais simples que funciona na maioria dos casos. Chamar algo de CodeSmell não é um ataque; é simplesmente um sinal de que é necessário um olhar mais atento.

Então, o que significa que os comentários são cheiros de código: significa que, quando você vê um comentário, deve fazer uma pausa e pensar: "Hmmm, sinto uma dica de que algo pode ser melhorado". Talvez você possa renomear uma variável, executar o "método de extração" - refatoração - ou talvez o comentário seja realmente a melhor solução.

É isso que significa que os comentários têm cheiro de código.

EDIT: Acabei de me deparar com estes dois artigos, o que explica melhor do que eu:

• Desculpas no código
• Para precisar de comentários

Eu acho que a regra é bem simples: imagine um completo estranho vendo seu código. Você provavelmente será um estranho ao seu próprio código em 5 anos. Tente minimizar o esforço mental para entender seu código para esse estranho.

Uma boa idéia para ter os comentários certos é começar escrevendo comentários.

// This function will do something with the parameters, 
// the parameters should be good according to some rules.
myFunction(parameters)
{
    // It will do some things to get started.

    // It will do more with the stuff.

    // It will end doing things with the stuff.
}

Isso permite que você extraia métodos facilmente para se livrar dos comentários,
deixe o código dizer essas coisas ! Veja como isso é reescrito (recortar / colar) de uma maneira muito agradável:

// This function will do something with the parameters, 
// the parameters should be good according to some rules.
myfunction(parameters)
{
  var someThing = initializedWithSomething;

  doSomethingWith(someThing);

  doMoreWith(someThing);

  endDoingThingsWith(someThing);

  return someThing;
}

// This function will do some things to get started,
// the parameters should be good according to some rules.
doSomethingWith(parameters)
{
  parameters.manipulateInSomeWay();
  ... etc ...
}

... etc ...

Para coisas que não podem ser separadas, não extraia métodos e digite o código nos comentários.

É isso que eu vejo como uma maneira útil de manter o mínimo de comentários, é realmente inútil comentar cada linha ... Apenas documente uma única linha se for sobre uma inicialização de valor mágico ou onde faz sentido.

Se os parâmetros forem usados ​​demais, eles deverão ser membros privados da sua classe.

Eu acho que a resposta é a usual "Depende". Comentar código apenas para comentar é um cheiro. Comentar o código porque você está usando um algoritmo obscuro que é uma ordem de magnitude mais rápido economiza o programador de manutenção (geralmente eu 6 meses depois que o escrevi) meio dia examinando o código para determinar o que está fazendo.

// Dear me in the future. Please, resolve this problem.

ou

// You think this code was written by somebody else. 
// No, it wasn't. You ([some name]) did it.

Comentários de código definitivamente não são um "cheiro de código". Essa crença geralmente vem do fato de que os comentários podem ficar obsoletos (desatualizados) e podem ser difíceis de manter. No entanto, ter bons comentários que expliquem por que o código está fazendo algo de uma certa maneira pode (e geralmente é) importante para manutenção.

Bons comentários facilitam a compreensão do que o código está fazendo e, mais importante, por que ele está fazendo de uma maneira específica. Os comentários devem ser lidos pelos programadores e devem ser claros e precisos. Um comentário difícil de entender ou incorreto não é muito melhor do que não ter comentado nada.

Adicionar comentários claros e precisos ao seu código significa que você não precisa confiar na memória para entender o "o quê" e o "porquê" de uma seção do código. Isso é mais importante quando você olha para esse código mais tarde, ou alguém deve olhar para o seu código. Como os comentários se tornam parte do conteúdo textual do seu código, eles devem seguir os bons princípios de escrita, além de serem claramente escritos.

Para escrever um bom comentário, você deve fazer o possível para documentar a finalidade do código (o porquê, não como) e indicar o raciocínio e a lógica por trás do código da maneira mais clara possível. Idealmente, os comentários devem ser escritos ao mesmo tempo em que você escreve o código. Se você esperar, provavelmente não voltará e os adicionará.

Sams ensina-se Visual C # 2010 em 24 horas , pp 348-349.

Se o código foi escrito de uma maneira específica para evitar um problema presente em uma biblioteca (uma biblioteca de terceiros ou uma biblioteca que acompanha o compilador), faz sentido comentá-lo.
Também faz sentido comentar o código que precisa ser alterado em versões futuras, ou ao usar uma nova versão de uma biblioteca, ou ao passar do PHP4 para o PHP5, por exemplo.

Mesmo o livro mais bem escrito ainda provavelmente tem uma introdução e títulos de capítulo. Os comentários no código bem documentado ainda são úteis para descrever conceitos de alto nível e explicar como o código está organizado.

De menção honrosa é o anti-padrão:

Tenho a impressão de que, às vezes, os preâmbulos de licença do FLOSS são frequentemente usados no lugar da documentação do arquivo. A GPL / BSDL produz um bom texto de preenchimento e, depois disso, você raramente vê qualquer outro bloco de comentários.

Não concordo com a ideia de que escrever comentários para explicar o código seja ruim. Isso ignora completamente o fato de que o código possui bugs. Pode ficar claro o que o código faz sem comentários. É menos provável que fique claro o que o código deve fazer. Sem comentários, como você sabe se os resultados estão errados ou estão sendo usados ​​incorretamente?

Os comentários devem explicar a intenção do código, para que, se houver um erro, alguém lendo o código dos comentários + tenha a chance de encontrá-lo.

Geralmente, me pego escrevendo comentários embutidos antes de escrever o código. Dessa forma, fica claro o que estou tentando escrever código e reduz a perda de um algoritmo sem realmente saber o que você está tentando fazer.

Comentários inseridos porque alguém acha que é bom ter 700 linhas em um método são um cheiro.

Os comentários que existem porque você sabe que, se não fizer um comentário, alguém cometerá o mesmo erro mais uma vez.

Comentários inseridos porque alguma ferramenta de análise de código exige que também seja um cheiro.

Pessoas que nunca colocam um comentário ou escrevem uma pequena ajuda para outros desenvolvedores também são um cheiro. Estou impressionado com quantas pessoas não escrevem coisas, mas depois se viram e reconhecem que não conseguem se lembrar do que fizeram há três meses. Não gosto de escrever documentos, mas gosto de contar às pessoas a mesma coisa repetidamente e menos ainda.

Vou responder com uma pergunta minha. Você pode encontrar o bug no código não comentado abaixo?

tl; dr: A próxima pessoa a manter seu código pode não ser tão divina quanto você.

 [org 0x7c00]

 main:
  mov ah, 0x0e
  mov bx, string
  call strreverse
  call print

 stop:
  jmp $

 strreverse:
  pusha
  mov dx, bx
  mov cx, 0

 strreverse_push:
  mov al, [bx]
  cmp al, 0
  je strreverse_pop
  push ax
  add bx, 1
  add cx, 1
  jmp strreverse_push

 strreverse_pop:
  mov bx, dx

 strreverse_pop_loop:
  cmp cx, 0
  je strreverse_end
  pop ax
  mov [bx], al
  sub cx, 1
  add bx, 1
  jmp strreverse_pop_loop

 strreverse_end:
  popa
  ret

 print:
  pusha

 print_loop:
  mov al, [bx]
  cmp al, 1
  je print_end
  int 0x10
  add bx, 1
  jmp print_loop

 print_end:
  popa
  ret
 string:
  db 'Boot up', 0

 times 510 -( $ - $$ ) db 0
 dw 0xaa55

Você precisa manter um equilíbrio entre o código e os comentários ... Normalmente, tento adicionar alguns comentários que retomam um bloco de código. Não porque eu não seja capaz de entender o código (bem, isso também), mas porque posso ler mais rapidamente meu próprio código e localizar seções específicas nas quais as coisas importantes estão acontecendo.

Enfim, meus próprios critérios pessoais são "em caso de dúvida, comente". Prefiro ter uma linha redundante do que uma linha completamente enigmática que não vou conseguir entender. Sempre posso remover comentários em uma revisão de código depois de um tempo (e geralmente faço)

Além disso, comentários são bastante úteis para adicionar "advertências" como "Cuidado! Se o formato da entrada não for ASCII, esse código precisará ser alterado!"

Lendo isso, lembro-me de algo que li pela primeira vez (de uma lista mais longa, preservada ao tirar fotocópias) algumas décadas atrás:

Programadores de verdade não escrevem comentários - se foi difícil escrever, deve ser difícil ler

Um cheiro um pouco mais velho parece.

Eu acho que o código comentado começa muito mal na vida. Hoje não sei, mas quando aprendi a programar na escola, recebi atribuições da natureza de "Escreva um programa que imprima os números de um a dez em linhas separadas. Certifique-se de comentar seu código". Você seria marcado se não adicionasse comentários porque comentar seu código é uma BOA COISA.

Mas o que há a dizer sobre um processo tão trivial? Então você acaba escrevendo o clássico

i++; // add one to the "i" counter.

apenas para obter uma nota decente e, se você tiver alguma dúvida, formar instantaneamente uma opinião muito baixa dos comentários do código.

Comentar código não é uma BOA COISA. É uma coisa às vezes necessária, e Thomas Owens na resposta superior fornece uma excelente explicação das situações em que é necessário. No entanto, essas situações raramente surgem em tarefas do tipo lição de casa.

De muitas maneiras, adicionar um comentário deve ser considerado uma opção de último recurso, quando o que precisa ser dito não pode ser dito claramente nas partes ativas da linguagem de programação. Embora a nomeação de objetos possa ficar obsoleta, vários mecanismos de falta de feedback humano e computador facilitam o esquecimento de manter comentários e, consequentemente, os comentários ficam obsoletos muito mais rapidamente do que o código ativo. Por esse motivo, sempre que uma opção é possível, a alteração do código para torná-lo mais claro deve sempre ser preferida à anotação de código pouco claro com comentários.

É claro que os comentários são um cheiro de código ...

todo programador sabe que todos acabamos ficando loucos devido à quantidade de trabalho, depuração ou loucura que encontramos.

"Fazem isto!" seu gerente de projeto diz.

Você responde: "Isso não pode ser feito".

Eles dizem: "Então encontraremos alguém para fazer isso".

Você diz: "OK, talvez isso possa ser feito".

E depois passe o próximo número X de dias .. semanas .. meses .. tentando descobrir isso. Durante todo o processo, você tentará e falhará, e tentará e falhará. Todos nós fazemos isso. A resposta verdadeira é que existem dois tipos de programadores, aqueles que comentam e outros que não.

1) Aqueles que o fazem estão facilitando seu próprio trabalho documentando para referência futura, comentando rotinas com falha que não funcionaram (o cheiro não é excluí-las depois de encontrar a que funciona) ou quebrando o código com comentários formatação para espero torná-lo um pouco mais fácil de ler ou compreender. Sério, não posso culpá-los. Mas no final, eles se encaixam e você tem o seguinte: // dammit this code sucks! swear! curse! i hate it! i am going to write something here to vent my anger!!!!

2) Aqueles que não estão fingindo ser um super-herói ou estão vivendo em uma caverna . Eles simplesmente têm um desprezo imprudente pelos outros, eles mesmos, e podem se importar menos com o código, ou com o significado que isso possa ter para mais tarde.

Agora, não me interpretem mal. As variáveis ​​e funções auto-documentadas podem evitar isso completamente. E confie em mim: você nunca pode limpar o código o suficiente. Mas a verdade simples é que, enquanto você mantiver backups, você SEMPRE poderá excluir comentários.

Eu diria que não usar alguns comentários no seu código é um cheiro de código. Embora eu concorde que o código deva se auto-documentar o máximo possível, você chega a um certo ponto em que verá um código que não faz sentido, independentemente de quão bem o código esteja escrito. Eu já vi algum código em aplicativos de negócios em que os comentários são praticamente obrigatórios porque:

1. Você precisa fazer algo caso a caso e não há uma boa lógica para isso.
2. O código provavelmente será alterado em um ano ou dois quando as leis forem alteradas e você desejar encontrá-lo novamente rapidamente.
3. Alguém editou o código no passado porque não entendia o que o código estava fazendo.

Além disso, os guias de estilo da empresa podem solicitar que você faça algo de uma certa maneira - se eles disserem que você poderia ter comentários descrevendo o que os blocos de código em uma função estão fazendo, inclua os comentários.

Há uma grande diferença fundamental entre comentários e código: os comentários são uma maneira de as pessoas comunicarem idéias a outras pessoas, enquanto o código é destinado principalmente ao computador. Existem muitos aspectos no "código" que também são apenas para humanos, como nomeação e recuo. Mas os comentários são escritos estritamente para humanos, por humanos.

Portanto, escrever comentários é tão difícil quanto qualquer comunicação humana escrita! O escritor deve ter uma concepção clara de quem é o público e de que tipo de texto será necessário. Como você pode saber quem lerá seus comentários em dez, vinte anos? E se a pessoa for de uma cultura completamente diferente? Etc. Espero que todos entendam isso.

Mesmo dentro da pequena cultura homogênea em que vivo, é tão difícil comunicar idéias a outras pessoas. A comunicação humana geralmente falha, exceto por acidente.

Eu tenho que concordar com seu colega de trabalho. Eu sempre digo que se eu comentar meu código, isso significa que eu estou preocupado que eu não será capaz de descobrir o meu próprio código no futuro. Este é um mau sinal.

A única outra razão pela qual eu coloco comentários no código é chamar algo que parece não fazer sentido.

Esses comentários geralmente assumem a forma de algo como:

//xxx what the heck is this doing??

ou

// removed in version 2.0, but back for 2.1, now I'm taking out again

Comentários de código que fornecem, onde aplicável, unidades de argumentos e retornos de função, campos de estrutura e até variáveis ​​locais podem ser muito úteis. Lembre-se do Mars Orbiter!

Aqui está minha regra de ouro:

• Escreva o código e armazene um breve resumo do código em um documento separado.
• Deixe o código em paz por vários dias para trabalhar em outra coisa.
• Retorne ao código. Se você não conseguir entender imediatamente o que deve fazer, adicione o resumo ao arquivo de origem.

Eduque seu colega de trabalho sobre a técnica de programação alfabetizada .

Não, os comentários não são um cheiro de código, são apenas uma ferramenta que pode ser abusada.

Exemplos de bons comentários:

// Acho que isso está em cm. É necessária mais investigação!

// Essa é uma maneira inteligente de fazer X

// É garantido que a lista não esteja vazia aqui