Comentários desatualizados são um mito urbano?

38

Eu sempre vejo pessoas afirmando que "os comentários tendem a ficar desatualizados". A coisa é, acho que já vi talvez dois ou três comentários desatualizados 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? Algumas indústrias são mais propensas a esse problema do que outras? Você tem exemplos específicos de comentários desatualizados recentes que você viu? Ou são comentários desatualizados mais de um problema teórico do que um real?

    
por Karl Bielefeldt 19.04.2011 / 15:47
fonte

12 respostas

33

Constantemente

Eu realmente não posso acreditar que sou o único nadando em comentários desatualizados e enganosos. Na chance, isso ajuda na compreensão:

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

Eu faço partes iguais de P & D e trabalho de manutenção. O R & D é um código novo, geralmente algo que é um pouco fora do caminho comum. Muitos de meus colegas acreditam em colocar muitas explicações comentadas quando tentam algo para o qual já não existe uma biblioteca. Como o índice de comentário para código é maior que o normal, há apenas mais oportunidades para que as coisas saiam de sincronia.

O código de manutenção ... Sou um mantenedor ativo em um sistema com mais de 10 anos e outro que está acima de 5. O código e os comentários de 10 anos são atrozes, como seria de se esperar. Ao longo de 10 anos você tem muitas mãos na base de código e ninguém tem ideia de como tudo funciona mais. O código e os comentários de 5 anos são muito bons porque o volume de negócios da equipe tem sido muito baixo.

Eu trabalho quase todos os serviços, até nossos produtos são altamente personalizados para um cliente em particular.

Exemplos específicos:

  • Comentários descrevendo a melhoria de desempenho de uma determinada metodologia, 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 em cima do código com comentários (quem sabe quantos anos estão lá).

Em tudo isso, você vê uma tendência de simplesmente não manter os comentários e o código no mesmo nível do software. Os IDEs e os hábitos básicos do desenvolvedor não ajudam nisso, meus olhos foram treinados para passar rapidamente por eles. Eu acho que o comentário ultrapassado é relativamente barato para evitar projetos em campo verde e ativos. Se você conseguir manter a relação código / comentário alta, não é grande coisa para mantê-los atualizados. É um pouco mais difícil justificar caçar essas coisas quando você está orçado em x horas para corrigir um bug em um sistema de produção.

    
por 19.04.2011 / 18:02
fonte
18

"comments tend to become outdated."

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

The thing is, I think I have seen maybe two or three outdated comments my entire career.

Eu acredito que deveria ser perfeitamente possível trabalhar em um ambiente onde todos cuidam bastante dos comentários e os mantêm. É apenas um pequeno esforço extra para examinar 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 perceba imediatamente, eles eram comentários ruins de qualquer maneira, e não deveriam ter sido adicionados em primeiro lugar (ou pelo menos não estavam lá).

Além disso, geralmente, juntamente 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 ainda não experimentei. Toda vez que encontro um comentário desatualizado, vejo claramente o que mudou e apenas atualizo o comentário de acordo 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 participants [out of 28] reported that they get their main information from source code and inline comments whereas only four stated that documentation is their main source of information.

Isto está de acordo com a sua suspeita de que 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 a documentação desatualizada e os comentários desatualizados .

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

    
por 19.04.2011 / 15:58
fonte
17

Comentários desatualizados são um cheiro de trabalho. É como ter testes de unidade desatualizados ou negligenciados - isso mostra que os bons processos que antes estavam ativos na loja estão se degenerando para a codificação cowboy. A "cultura de engenharia" adequada de tomar o tempo para fazer as coisas corretamente foi quebrada. O projeto / empresa provavelmente entrará 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 tanto. Mas em lojas mais típicas e menos bem administradas, isso corre paralelo ao resto do caos.

    
por 20.04.2011 / 01:23
fonte
10

Os comentários são como testes, eles são muito bons quando estão atualizados, mas podem dificultar ainda mais a compreensão 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 eu desconsidero os comentários completamente, pois eles geralmente são fonte de confusão em vez de ajuda.

    
por 19.04.2011 / 16:00
fonte
10

Comentários desatualizados geralmente aparecem no JavaDoc:

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

Além disso, às vezes os comentários definem coisas como "faça isso aqui para desempenho", quando a maioria das considerações de desempenho tende a se tornar obsoleta ainda mais rapidamente do que o próprio código.

    
por 19.04.2011 / 16:02
fonte
4

Eu lido com comentários desatualizados de tempos em tempos. Certamente não é um mito urbano. As pessoas mencionam isso em listas de piores práticas, não porque isso o atinja 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 descrever o comportamento do método próximo à sua chamada e não perto da declaração do método. Acontece quando alguém extrai um longo pedaço de código em um método que é chamado apenas uma vez no momento e, em seguida, 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 nesses métodos ao longo dos anos, lidando com mudanças de especificação e corrigindo bugs, e eventualmente você acaba com um método que não classifica a lista e lança uma exceção quando encontra o recurso vazio. Portanto, o comentário acima é um comentário desatualizado que eventualmente lhe custará algum tempo no depurador. Isso acontece em algumas bases de código.

    
por 19.04.2011 / 20:17
fonte
3

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

Eu trabalhei com um monte de código legado e os comentários às vezes não são nem de perto relevantes.

    
por 19.04.2011 / 18:23
fonte
2

Na maioria das vezes, minha experiência combina com a sua, mas eu encontrei 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 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 entrega original fizeram parte da mentalidade de "apenas mudar o que realmente precisa ser mudado", o que em si 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.

    
por 19.04.2011 / 15:58
fonte
2

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

//TODO: In 15 years AND NO SOONER... actually implement this method.
    
por 19.04.2011 / 16:01
fonte
2

Últimos 3 projetos em que trabalhei Passei vários dias em cada remoção de 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 eu já tirei dos outros, geralmente depois de ficarem sem manutenção por um tempo e os donos originais terem ido e / ou relutado ou incapazes de fazer a devida entrega.

    
por 20.04.2011 / 08:51
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 tem que incluir comentários para eles estarem desatualizados. Em segundo lugar, o código que foi 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 estragar uma grande parte de um aplicativo e perder muito do seu tempo.

    
por 19.04.2011 / 15:59
fonte
0

Em uma organização que gera muito código, é difícil manter os comentários em sincronia. A melhor maneira de entender o que está acontecendo é usando softwares que desenham o fluxograma de controle do módulo em que você está trabalhando. Essa é a única maneira de ter uma idéia do que o software faz.

    
por 20.04.2011 / 04:40
fonte

Tags