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?
comments
anti-patterns
Fishtoaster
fonte
fonte
Respostas:
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.
fonte
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.
fonte
Os comentários devem explicar o porquê, não como.
How
os 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:
depois de:
fonte
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:
fonte
SomebodyScrewedAroundWithDatabaseException
... #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):
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:
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.
fonte
} //end while
significa apenas que o início do loop while está tão distante que você nem consegue vê-lo, e não há dicas de que o código que você está visualizando esteja em um loop. Refatoração pesada deve ser seriamente preferida a comentários sobre como o código está estruturado.} // end while
comentários podem ser um salva-vidas.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.
fonte
Em alguns casos, nenhuma boa nomeação, refatoração etc. pode substituir um comentário. Veja este exemplo do mundo real (o idioma é Groovy):
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:
fonte
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:
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:
fonte
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.
fonte
Uma boa idéia para ter os comentários certos é começar escrevendo comentários.
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:
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.
fonte
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.
fonte
ou
fonte
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.
fonte
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.
fonte
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.
fonte
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.
fonte
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.
fonte
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.
fonte
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ê.
fonte
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!"
fonte
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:
Um cheiro um pouco mais velho parece.
fonte
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
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.
fonte
É 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.
fonte
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:
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.
fonte
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.
fonte
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:
ou
fonte
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!
fonte
Aqui está minha regra de ouro:
fonte
Eduque seu colega de trabalho sobre a técnica de programação alfabetizada .
fonte
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
fonte
Assert(list.IsEmpty)
?Assert(!list.isEmpty())
não é exatamente um contrato, como no terceiro comentário, mas simplesmente um comportamento (por exemplo, "lançar IllegalArgumentException se o argumento estiver vazio") que deve ser testado por unidade como qualquer outra lógica do programa. Observe a diferença sutil no comentário, que indica quando o método pode ser usado, mas não especifica nenhum comportamento se a pré-condição não for atendida. Ainda melhor do que o comentário seria impor contratos em tempo de compilação. Mas isso excede o escopo da minha resposta;)Assert
s, pois eles descrevem coisas que nunca deveriam acontecer, mesmo que a API pública receba argumentos inválidos.