Comentários desatualizados são um mito urbano?

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?

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.

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

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.