É bom manter os comentários sobre correções no código?

Minha equipe está usando casos claros como controle de versão. O projeto em que estou trabalhando não é iniciado 7-8 anos atrás. Durante toda a vida útil do projeto, tivemos vários lançamentos de service packs de correções de bugs, etc. Os problemas são rastreados usando o sistema de rastreamento de bugs e a maioria das pessoas que trabalham nas bugs segue uma rotina de anexar o comentário em START / Bloco END com a data, autor, identificação do bug etc.

Eu sinto que isso é irrelevante e torna o código desorganizado e desconfortável de manter, e essas são as coisas que devem fazer parte dos comentários / etiquetas de check-in etc., onde podemos manter informações adicionais sobre o ciclo de vida do produto de trabalho.

Qual é a melhor prática a ser seguida?

Alguns dos revisores do código insistem em comentar os erros e as correções para facilitar sua vida. No meu entendimento, eles devem revisar os arquivos mapeando-os para uma visualização e obter o log de alterações da filial e revisá-los. Seria útil se eu pudesse obter algumas práticas recomendadas para enviar o código atualizado para revisão.

O problema de adicionar a correção de bug como um comentário ao código é que você não obtém a história completa. Se eu vir um pedaço de código perfeitamente fino com a tag "esta é uma correção para o bug blah ", minha primeira reação seria dizer "e daí?". O código está lá, funciona. A única coisa que preciso saber para manter o código é um comentário que me diz o que faz.

Uma prática melhor seria adicionar referências de correções de erros nos logs de confirmação do SCM. Dessa forma, você vê qual é o erro, onde foi introduzido e como foi corrigido. Além disso, quando chegar a hora de uma liberação, você pode simplesmente extrair os logs do SCM e adicionar um marcador indicando que houve um erro e que foi corrigido. Se outra ramificação ou versão apresentar o mesmo bug, é fácil localizar a correção e reaplicar se for realmente a mesma coisa.

Tendo dito tudo isso, eu também concordo com a resposta de Charles. Se o motivo de um pedaço de código não for óbvio, informe o mantenedor de que o código está lá por um motivo e deve ser tratado com cuidado.

Principalmente má prática. Não direi que isso nunca deve ser feito. Ocasionalmente, você encontra algo como um bug em uma API externa que precisa ser contornada. A solução alternativa pode parecer completamente com morte cerebral se você não souber sobre o bug subjacente. Nesse caso, pode ser uma boa idéia documentar o bug no código para que os colegas de trabalho ou o seu eu posterior não tentem "consertar" o código obviamente morto do cérebro.

Má prática. Os comentários ficarão desatualizados e desorganizarão o código. As informações ainda estão disponíveis no histórico da versão do seu sistema SCC, se necessário.

Parece uma má prática. E se a sua organização decidir migrar para outro sistema de rastreamento de bugs? Não amarre seu produto com muita força às ferramentas que você está usando no momento. Em vez de se referir a IDs de bug específicos, e as razões pelas quais o código parece não serem claras, motive sua decisão de design com comentários no código.

Minha primeira reação seria não se repetir, então retire-o do código e entre nos logs do SCM. Tivemos uma discussão semelhante aqui sobre o comentário de revisão de funções, nomes de autores e datas de criação de arquivos e funções. No passado (antes de o SCM ser usado), todas essas informações eram mantidas nos arquivos para poder reconstruir a evolução de um arquivo.

Cerca de metade dos desenvolvedores deseja que essas informações possam ter todas as informações em um único local (isso as aciona para procurar alterações no SCM). A outra metade dos desenvolvedores não inicia a busca por pistas sobre o que mudou no código, mas a partir do SCM, para que não precisem das informações no código. Ainda temos que decidir o que fazer com esses comentários. Depende muito da maneira como as pessoas estão trabalhando e algumas são muito teimosas em deixar seus métodos conhecidos. A mesma coisa sobre comentar o bloco de código e deixá-los no código para sempre.

Apenas para adicionar ao que Dyaster et al. Como dito, embora o JIRA tenha habilidades realmente boas para exibir as alterações associadas às correções, o melhor lugar para documentar uma correção é em um caso de teste. Se o código não estiver claro sem um comentário indicando qual bug foi corrigido, isso é "cheiro de código". Dito isto, se você não tiver tempo para limpar o cheiro, o comentário deve se referir ao caso de teste, onde deve ser muito mais óbvio o motivo pelo qual o código está fazendo o que está fazendo. Se você não tiver tempo para escrever um caso de teste explicando a correção do bug, o bug ainda não foi corrigido, apenas foi adiado.

Concordo em adicionar IDs de correção de erros nas mensagens de confirmação, e não dentro do próprio código. Os rastreadores de erros que rastreiam automaticamente as mensagens de confirmação para os IDs de erros são muito úteis.

Além disso, você pode usar o comando culpar / anotar / elogiar do seu sistema de controle de versão para ajudar a substituir esses comentários. Então, quando você executa algo como:

vcs blame file.ext

você pode ver informações úteis, geralmente incluindo quem alterou cada linha, quando a alteraram e o ID de confirmação. No id de confirmação, você pode obter a mensagem completa, que deve incluir o ID do bug.

Os bons sistemas de VCS permitem ignorar o espaço em branco ao calcular quem modificou uma linha.

Não sei o que o Clear Case possui para esse recurso.