Comentários desatualizados são um mito urbano?

38

Vejo constantemente pessoas afirmando que "os comentários tendem a ficar desatualizados". Acho que já vi dois ou três comentários desatualizados em toda a minha carreira. Informações desatualizadas em documentos separados acontecem o tempo todo, mas, na minha experiência, comentários desatualizados no próprio código são extremamente raros.

Acabei de ter sorte com quem trabalho? Alguns setores são mais propensos a esse problema do que outros? Você tem exemplos específicos de comentários desatualizados recentes que você viu? Ou os comentários desatualizados são mais um problema teórico do que real?

Karl Bielefeldt
fonte
30
Acordado. Código desatualizado transformado em comentário, agora isso é algo que vejo muito - e gostaria de ver menos.
pyvi
8
Eu vejo mais falta de comentários do que qualquer coisa. Combinado com más convenções de nomes, é uma diversão tentar ler algumas das coisas com as quais trabalho.
precisa
2
Eu já vi muitos comentários desatualizados, alguns eram simplesmente MAL enganadores. Definitivamente, nenhum mito, mas é principalmente válido para projetos mantidos por muitas pessoas e / ou por um longo tempo, amplificados pela complexidade. No entanto, aprendi a confiar no código, não nos comentários (quase nunca os leio se excederem mais de uma linha).
MaR
Eu tenho trabalhado principalmente com um código legado muito antigo ao longo de toda a minha carreira. Houve cerca de uma dúzia de vezes em que tive alguns problemas graves relacionados a comentários desatualizados em um código Fortan77 de 30 anos, mas era uma porcentagem próxima de zero do código em que os comentários eram adequados. Então, eu concordo, a escala de um problema deve ter sido exagerada.
SK-logic
Apenas minha sorte, eu já vi várias no ano desde que publiquei isso. Acho que subconscientemente aprendi a não confiar neles, a corrigi-los e seguir em frente, sem pensar o suficiente para colocar em minha memória de longo prazo.
Karl Bielefeldt

Respostas:

33

Constantemente

Realmente não posso acreditar que sou o único a comentar comentários desatualizados e enganosos. Na hipótese de isso ajudar a entender:

Provavelmente depende mais importante da idade do código. O próximo fator seria a rotatividade da equipe.

Faço partes iguais de pesquisa e desenvolvimento e trabalho de manutenção. O P&D é um novo código, geralmente coisas um pouco fora do caminho comum. Muitos de meus colegas acreditam em colocar muitas explicações comentadas ao tentar algo que ainda não existe em uma biblioteca. Como a proporção de comentário para código é mais alta que o normal, há apenas mais oportunidades para que as coisas fiquem fora de sincronia.

O código de manutenção ... Sou um mantenedor ativo em um sistema com mais de 10 anos e outro com mais de 5. O código e os comentários de 10 anos são atrozes, como seria de esperar. Ao longo de 10 anos, você tem muitas mãos na base de código e ninguém tem idéia de como tudo funciona mais. O código e os comentários de 5 anos são muito bons porque a rotatividade da equipe tem sido bastante baixa.

Trabalho em quase todos os serviços, até nossos produtos são altamente personalizados para um cliente específico.

Exemplos específicos:

  • Comentários descrevendo a melhoria de desempenho para uma metodologia específica, como evitar uma cópia na memória. Um grande negócio quando uma máquina topo de linha em um Pentium 2 com MBs de RAM, mas dificilmente um problema agora.

  • TODOs

  • Blocos de código copiado e colado, incluindo comentários. O comentário pode ter feito sentido em sua localização original, mas dificilmente faz sentido aqui

  • Blocos de comentários sobre o código comentado (quem sabe quantos anos se passaram lá).

Em tudo isso, você vê uma tendência de não manter os comentários e o código no mesmo nível do software. IDEs e hábitos básicos de desenvolvedores não ajudam nisso, meu olho foi treinado para passar por eles. Penso que comentários desatualizados são relativamente baratos para evitar em projetos verdes e ativos. Se você pode manter a proporção de código / comentário alta, não é importante mantê-los atualizados. É um pouco mais difícil justificar a busca dessas coisas quando você está orçado x horas para uma correção de bug em um sistema de produção.

Steve Jackson
fonte
Então, basicamente, você está dizendo que simplesmente ignora completamente os comentários, porque já é uma bagunça muito grande, apenas piorando a sua situação. Dificilmente surpreendente.
91111 Steven Jeuris
5
@ Steven - Eu pessoalmente, não. Eu acredito muito em melhorias incrementais. Eu já vi um monte de código completamente indecifrável se transformar em algo bastante decente, com esforço gradual suficiente. Mas ignorar é certamente a norma na minha experiência. É muito compreensível quando você encontra várias classes de 10000 linhas entrelaçadas, com semanas de problemas para catalogar, que comentários desatualizados tendem a cair no final da lista de prioridades.
19611 Steve Jackson
1
@ Steve: Na sua situação, eu simplesmente criaria um script que remove todos os comentários e começaria a comentar do zero, quando necessário. :)
Steven Jeuris
1
a base de código principal onde eu costumava trabalhar era pelo menos metade dos comentários e código raramente comentado. Comentários desatualizados eram um fato da vida, comentários corretos eram extremamente raros e eu nem começarei a comentar a documentação !!! vista ... Após este trabalho eu aprendi que menos é bom, se você código precisa comentário, ele provavelmente precisa de um refactor para tornar as coisas mais óbvias ...
Newtopian
4
Eu já vi alguns exemplos terríveis de Blocks of copy-pasted code including comments. Comment may have made sense in its original location, but hardly makes sense here. Comentários em nível de classe falando sobre uma classe diferente, por exemplo.
Peter Taylor
18

"os comentários tendem a ficar desatualizados."

Eu já vi isso acontecendo com frequência suficiente para saber que isso pode ser um problema.

Acho que já vi dois ou três comentários desatualizados em toda a minha carreira.

Eu acredito que deveria ser perfeitamente possível trabalhar em um ambiente onde todos cuidem o suficiente dos comentários e os mantenham. É apenas um pequeno esforço extra para analisar os comentários próximos ao código que você está editando e atualizá-los quando apropriado. Caso os comentários estejam tão distantes que você não os note imediatamente, eles eram comentários ruins de qualquer maneira e não deveriam ter sido adicionados em primeiro lugar (ou pelo menos não existem).

Além disso, geralmente junto com a afirmação de que os comentários tendem a ficar desatualizados, segue a afirmação de que isso reduz a legibilidade e confunde as pessoas. Isso é algo que eu ainda não experimentei. Toda vez que encontro um comentário desatualizado, vejo claramente o que mudou e apenas atualizo o comentário para representar o código mais recente, embora com algum esforço extra.


Um estudo recente de Roehm et al. 2012 observa o seguinte:

21 participantes [de 28] relataram que obtêm suas principais informações do código fonte e comentários embutidos, enquanto apenas quatro afirmaram que a documentação é sua principal fonte de informações.

Isso está de acordo com sua suspeita de que os comentários no próprio código geralmente ainda são considerados muito úteis. Isso indica que uma linha clara deve ser traçada entre documentação desatualizada e comentários desatualizados .

Roehm, T., Tiarks, R., Koschke, R. e Maalej, W. (2012, junho). Como desenvolvedores profissionais compreendem software ?. Em Anais da Conferência Internacional de 2012 sobre Engenharia de Software (pp. 255-265). IEEE Pressione.

Steven Jeuris
fonte
À medida que me tornei melhor, descobri que preciso de menos comentários para entender o que o código faz no código plug-in típico do plug-n.
Paul Nathan
3
@ Paul Nathan, os comentários nunca devem descrever o que o código faz - o código descreve isso melhor. Comentários existem para explicar por que o código faz o que faz.
SK-lógica
2
@ SK-logic: Embora eu entenda o argumento, acredito que seja muito amplo. Os comentários de uma função (ou parágrafo / bloco de código) podem esclarecer muito mais (e mais rapidamente) o que a função faz do que seu nome. Isso é especialmente necessário para funções públicas. Por mais fácil que o código possa ser lido, a leitura de uma explicação de duas linhas do código de 10 linhas é ainda mais rápida. Imagine trabalhar com sua API favorita, que não possui nenhuma documentação "o quê" . Você teria muito menos certeza sobre sua funcionalidade.
91111 Steven Jeuris
sim, eu não incluí uma documentação (por exemplo, Javadoc) - ela é muito estruturada para ser chamada apenas de " comentários ".
SK-lógica
17

Comentários desatualizados são um cheiro de trabalho. É como ter testes de unidade desatualizados ou negligenciados - mostra que os bons processos que antes estavam ativos na loja estão degenerando na codificação de cowboys. A "cultura de engenharia" adequada de reservar um tempo para fazer as coisas corretamente quebrou. O projeto / empresa provavelmente está entrando em dívida técnica.

Em suma, sim, você teve sorte. Se você teve uma série de lojas razoavelmente bem administradas até agora em sua carreira, é bem possível não ver isso. Mas em lojas mais típicas e menos bem administradas, isso ocorre paralelamente ao resto do caos.

Bobby Tables
fonte
"Comentários desatualizados são um cheiro de trabalho". Muito bem colocado! Da mesma forma, o código de auto-documentação apenas sem comentários não é a solução, mas um 'hack' preguiçoso.
91111 Steven Jeuris
10

Os comentários são como testes, são muito bons quando atualizados, mas podem dificultar ainda mais o entendimento do código, se não houver.

Se você nunca viu comentários desatualizados, teve muita sorte.

A maioria das bases de código com as quais trabalhei está cheia de comentários desatualizados, e geralmente desconsiderei completamente os comentários, pois geralmente são fonte de confusão em vez de ajuda.

Kim.Net
fonte
Posso perguntar em quais indústrias você trabalhou? Gostaria de saber se isso é mais comum em alguns do que em outros.
19611 Karl Bielefeldt
Trabalhei em 3 países diferentes da Europa, principalmente como consultor de uma grande e pequena empresa. Ultimamente em uma casa de desenvolvimento de SaaS.
21411 Kim.Net
10

Comentários desatualizados costumam aparecer no JavaDoc:

  • Listando argumentos que não existem mais
  • Não explicando todos os argumentos (os ausentes foram provavelmente adicionados mais tarde)
  • Coisas semelhantes para exceções, etc.

Além disso, às vezes os comentários afirmam coisas como "faça isso aqui para obter desempenho" quando a maioria das considerações sobre desempenho tendem a ficar obsoletas ainda mais rápido que o próprio código.

Deckard
fonte
3
(Não é uma crítica - basta apresentar uma solução) Os avisos do IDE podem ajudar bastante a evitar isso. Se forem necessárias medidas mais drásticas, falhe na compilação em um aviso / erro de compilação javadoc.
Michael K
1
Isso poderia explicar por que não vi muitos. Eu nunca trabalhei em algum lugar que usa comentários no estilo JavaDoc.
Karl Bielefeldt
4
@ Michael, os avisos do IDE são úteis em casos leves. Nossa base de código herdada produz mais de 20.000 avisos do Checkstyle, muito além do limite em que você para de prestar atenção: - (((os IDEs, quando mal utilizados, podem contribuir significativamente para a miséria do Javadoc. A maior parte da porcaria do Javadoc em nossa base de código foi obviamente gerada automaticamente.
Péter Török
4

Eu lido com comentários desatualizados de tempos em tempos. Certamente não é um mito urbano. As pessoas o mencionam nas listas das piores práticas, não porque o acerte com muita frequência, mas porque, quando isso acontece, geralmente custa muito tempo e esforço.

Em nossa base de código, os comentários mais desatualizados são causados ​​pelo uso do (anti) padrão de descrição do comportamento do método próximo à sua chamada e não à declaração do método próximo. Isso acontece quando alguém extrai um longo código em um método que é chamado apenas uma vez no momento e depois comenta a chamada do método. Então você acaba com algo assim:

featureList = GetFeatures();

// Sorting features and deleting empty ones from the list...
ProcessFeatures(featureList);

E o método é declarado em algum lugar abaixo sem comentários. As pessoas mexem com esses métodos ao longo dos anos, lidando com alterações de especificação e correção de bugs e, eventualmente, você acaba com um método que não classifica a lista e gera uma exceção quando encontra o recurso vazio. Portanto, o comentário acima é um comentário desatualizado que acabará custando algum tempo no depurador. Isso acontece em algumas bases de código.

Dyppl
fonte
3

Pergunte a si mesmo isso. Você já mudou uma linha de código e não mudou os comentários associados ou adicionou novos?

Eu trabalhei com muito código legado e os comentários às vezes nem sequer são relevantes.

Bill Leeper
fonte
2

Na maioria das vezes, minha experiência corresponde à sua, mas deparei-me com um caso em que isso era verdade em toda a base de código. Era um aplicativo que havia sido escrito anos antes por uma loja de consultoria que não estava mais "em boas condições" com o cliente.

A empresa fez um trabalho excepcional comentando o código, mas os programadores que o mantiveram desde a transferência original faziam parte da mentalidade "apenas mudar o que absolutamente precisa ser mudado", o que por si só não é ruim. Infelizmente, eles mantiveram a mesma atitude em relação aos comentários, levando a uma grande desconexão entre os comentários e o código ao longo do tempo.

Dave Wise
fonte
2

Não vejo muitos comentários descritivos desatualizados, mas vejo muitos comentários do TODO que estão lá há anos. Eu gostaria que eles fossem cápsulas do tempo e dissessem algo assim:

//TODO: In 15 years AND NO SOONER... actually implement this method.
Morgan Herlocker
fonte
1
O problema neste caso é provavelmente o uso indevido de TODOs. Acredito que os TODOs devem ser usados ​​apenas quando o código estiver realmente funcional, mas melhorias poderão ser feitas posteriormente, portanto, esse TODO: implementtipo de comentário não deve existir e o fato de ninguém voltar realmente não importa tanto. Infelizmente, muitas pessoas não aderem a essa regra e concordo totalmente que gostaria de ver um comentário como você postado em algum código de produção em algum momento. Isso faria o meu dia.
pwny
1
Em C #, uso o NotImplementedException para esses fins.
91111 Steven Jeuris
2
@ pwny, eu só uso TODOs em coisas que pretendo escrever antes de fazer o check-in, para garantir que eu o cubra. Qualquer coisa a longo prazo pertence a um rastreador de bugs, na minha opinião.
19711 Karl Bielefeldt
@Karl Bielefeldt Isso também faz muito sentido.
Pwny #
2

Nos últimos 3 projetos em que trabalhei, passei vários dias removendo comentários desatualizados, enganosos e simplesmente inúteis da base de código. Sempre que possível e necessário, eu os substituo por comentários mais apropriados, mas na maioria das vezes é apenas uma questão de excluir o comentário e seguir em frente.

Eu fiz o mesmo em praticamente todas as bases de código que já substituímos por outros, geralmente depois de um tempo em que não era mantida e os proprietários originais desapareciam há muito tempo e / ou não queriam ou eram incapazes de fazer a devida transferência.

jwenting
fonte
1

Pode ser o declínio no uso de comentários. Quanto do código de alguém se qualifica? Por um lado, alguém realmente precisa incluir comentários para estar desatualizado. Segundo, o código comentado deve ser alterado. Não tenho certeza se uma alta porcentagem de código está qualificada.

Você só precisa confiar em um comentário ruim para arruinar uma grande parte de um aplicativo e perder muito tempo.

JeffO
fonte
0

Em uma organização que produz muito código, é difícil manter os comentários sincronizados. A melhor maneira de entender o que está acontecendo é usar softwares que desenham o diagrama de fluxo de controle do módulo em que você está trabalhando. Essa é a única maneira de manter uma ideia do que o software faz.

Gaurav Sehgal
fonte