Geralmente considero esses comentários uma prática ruim e acho que esse tipo de informação pertence aos logs de confirmação do SCM. Isso apenas torna o código mais difícil de ler na maioria dos casos.
No entanto , muitas vezes ainda faço algo assim para tipos específicos de edições.
Caso 1 - Tarefas
Se você usa um IDE como Eclipse, Netbeans, Visual Studio (ou tem alguma maneira de fazer pesquisas de texto em sua base de código com qualquer outra coisa), talvez sua equipe use algumas "tags de comentários" ou "tags de tarefas" específicas. Nesse caso, isso pode ser útil.
De vez em quando, ao revisar o código, adicionava algo como o seguinte:
// TOREVIEW: [2010-12-09 haylem] marking this for review because blablabla
ou:
// FIXME: [2010-12-09 haylem] marking this for review because blablabla
Eu uso diferentes tags de tarefas personalizadas que posso ver no Eclipse na visualização de tarefas para isso, porque ter algo nos logs de confirmação é uma coisa boa, mas não é suficiente quando você tem um executivo perguntando em uma reunião de revisão por que a correção XY foi completamente esquecida e escorregou. Portanto, em assuntos urgentes ou trechos de código realmente questionáveis, isso serve como um lembrete adicional (mas geralmente manterei o comentário curto e verificarei os logs de confirmação, porque É para isso que serve o lembrete, para que eu também não confunda o código Muito de).
Caso 2 - Patches de libs de terceiros
Se meu produto precisar empacotar um código de terceiros como fonte (ou biblioteca, mas reconstruído a partir da fonte) porque precisava ser corrigido por algum motivo, documentamos o patch em um documento separado, onde listamos essas "advertências" para referência futura, e o código fonte geralmente conterá um comentário semelhante a:
// [PATCH_START:product_name]
// ... real code here ...
// [PATCH_END:product_name]
Caso 3 - Correções não óbvias
Este é um pouco mais controverso e mais próximo do que seu desenvolvedor sênior está pedindo.
No produto em que trabalho no momento, às vezes (definitivamente não é uma coisa comum) temos um comentário como:
// BUGFIX: [2010-12-09 haylem] fix for BUG_ID-XYZ
Só fazemos isso se a correção de bug não for óbvia e o código for lido de maneira anormal. Pode ser o caso de peculiaridades do navegador, por exemplo, ou correções obscuras de CSS que você precisa implementar apenas porque há um erro no documento em um produto. Portanto, em geral, o vincularíamos ao nosso repositório de problemas internos, que conterá o raciocínio detalhado por trás da correção de bugs e os ponteiros para a documentação do bug do produto externo (por exemplo, um aviso de segurança para um defeito conhecido do Internet Explorer 6 ou algo parecido).
Mas, como mencionado, é bastante raro. E graças às tags de tarefa, podemos executá-las regularmente e verificar se essas correções estranhas ainda fazem sentido ou podem ser eliminadas gradualmente (por exemplo, se deixamos de lado o suporte ao produto com bugs que causou o bug).
Isto apenas em: Um exemplo da vida real
Em alguns casos, é melhor que nada :)
Acabei de encontrar uma enorme classe de computação estatística em minha base de código, onde o comentário do cabeçalho estava na forma de um registro de alterações com o usual yadda yadda: revisor, data, ID do bug.
No começo, pensei em desmantelar, mas notei que os códigos de bug não correspondiam não apenas à convenção de nosso rastreador de problemas atual, mas também ao do rastreador usado antes de eu ingressar na empresa. Então, tentei ler o código e entender o que a classe estava fazendo (não sendo estatístico) e também tentei desenterrar esses relatórios de defeitos. Por acaso, eles eram bastante importantes e teriam atrapalhado a vida do próximo cara para editar o arquivo sem conhecê-los bastante horrível, pois tratava de pequenos problemas de precisão e casos especiais baseados em requisitos muito específicos emitidos pelo cliente de origem na época. . Resumindo, se estes não estivessem lá, eu não saberia. Se eles não estivessem lá E eu tivesse uma melhor compreensão da classe,
Às vezes, é difícil acompanhar requisitos muito antigos como esses. No final, o que eu fiz ainda foi remover o cabeçalho, mas depois de entrar em um comentário em bloco antes de cada função incriminadora, descrevendo por que essas computações "estranhas" são solicitações específicas.
Então, nesse caso, eu ainda as considerava uma prática ruim, mas, felizmente, o desenvolvedor original os colocou! Teria sido melhor comentar o código claramente, mas acho que era melhor que nada.