Qual é a melhor abordagem para comentários de código embutido?

Estamos refatorando uma base de código herdada de 20 anos e estou tendo uma discussão com meu colega sobre o formato dos comentários no código (plsql, java).

Não há um formato padrão para comentários, mas na maioria dos casos as pessoas fazem algo assim no comentário:

// date (year, year-month, yyyy-mm-dd, dd/mm/yyyy), (author id, author name, author nickname) and comment

o formato proposto para comentários futuros e passados ​​que eu quero é:

// {yyyy-mm-dd}, unique_author_company_id, comment

Meu colega diz que precisamos apenas do comentário e devemos reformatar todos os comentários anteriores e futuros para este formato:

// comment

Meus argumentos:

• Digo, por motivos de manutenção, que é importante saber quando e quem fez uma alteração (até essas informações estão no SCM).
• O código está vivo e, por esse motivo, tem uma história.
• Como, sem as datas das alterações, é impossível saber quando uma alteração foi introduzida sem abrir a ferramenta SCM e pesquisar no longo histórico do objeto.
• porque o autor é muito importante, uma mudança de autores é mais credível do que uma mudança de autor
• Razões de agilidade, sem necessidade de abrir e navegar pela ferramenta SCM
• as pessoas teriam mais medo de mudar algo que alguém fez há 15 anos do que algo que foi criado ou alterado recentemente.
• etc.

Argumentos do meu colega:

• A história está no SCM
• Os desenvolvedores não devem estar cientes do histórico do código diretamente no código
• Os pacotes têm 15 mil linhas e comentários não estruturados tornam esses pacotes mais difíceis de entender

Qual você acha que é a melhor abordagem? Ou você tem uma abordagem melhor para resolver esse problema?

Comentários gerais

Eu acredito muito nos comentários: por que (não como) . Quando você começa a adicionar comentários sobre como você se depara com o problema, nada garante que os comentários sejam mantidos em relação ao código (o motivo geralmente não muda (a explicação do motivo pode ser aprimorada com o tempo)).

Da mesma forma, date / authorInfo não ganha nada em termos de por que o código foi feito dessa maneira; assim como a forma como ela pode se degenerar com o tempo, porque não há aplicação por nenhuma ferramenta. Além disso, as mesmas informações já estão armazenadas no sistema de controle de origem (para que você esteja duplicando o esforço (mas de uma maneira menos confiável)).

Analisando os argumentos:

Digo, por motivos de manutenção, que é importante saber quando e quem fez uma alteração (até essas informações estão no SCM).

Por quê. Nenhuma dessas coisas me parece importante para manter o código. Se você precisar conversar com o autor, é relativamente simples encontrar essas informações no controle de origem.

O código tem vida por esse motivo tinha uma história.

O histórico é armazenado no controle de origem.
Você também acredita que o comentário foi escrito por essa pessoa. Howos comentários tendem a se degradar com o tempo, de modo que esse tipo de história não se torna confiável. Os sistemas de controle de origem, por outro lado, manterão um histórico muito preciso e você poderá ver com precisão quando os comentários foram adicionados / removidos.

Porque sem a data da mudança, é impossível saber quando uma mudança foi introduzida sem abrir a ferramenta SCM e pesquisar no longo histórico do objeto.

Se você confiar nos dados em um comentário.
Um dos problemas com esse tipo de coisa é que os comentários se tornam incorretos em relação ao código. Voltar para a ferramenta correta para o trabalho. O sistema de controle de origem fará isso corretamente, sem a necessidade de intervenção do usuário. Se o seu sistema de controle de origem é um problema, talvez você precise aprender a usá-lo de maneira mais adequada (como essa funcionalidade geralmente é fácil) ou, se não o suporta, encontre um melhor sistema de controle de origem.

porque o autor é muito importante, uma mudança de authorx é mais credível do que uma mudança de autor

Todos os autores (além de você) são igualmente credíveis.

Razões de agilidade, não há necessidade de abrir e navegar na ferramenta SCM

Se a sua ferramenta de controle de fonte é tão onerosa, você está usando incorretamente ou (é mais provável) que você esteja usando o conjunto errado de ferramentas para acessar o sistema de controle de fonte.

as pessoas teriam medo de mudar algo que alguém fez há 15 anos, do que algo que foi feito de novo ...

Se o código durou 15 anos, é mais provável que seja mais sólido do que o código que durou apenas 6 meses sem a necessidade de revisão. O código estável tende a permanecer estável, o código de buggy tende a ficar mais complexo ao longo do tempo (porque o motivo é buggy, o problema não é tão simples quanto se pensava).

Ainda mais motivos para usar o controle de origem para obter informações.

A história está no SCM

Sim. Melhor razão ainda.

Os desenvolvedores não devem estar cientes do histórico do código diretamente no código

Se eu realmente precisar dessas informações, procurarei no controle de origem.
Caso contrário, não é relevante.

Pacotes tem 15k linhas de comprimento e comentários não estruturados são mais difíceis de entender

Os comentários devem ser uma descrição do motivo pelo qual você está fazendo algo.
Os comentários NÃO devem descrever como o código funciona (a menos que o algoritmo não seja óbvio).

Eu apoio fortemente o seu colega. Você não conseguirá ver o SCM de qualquer maneira se quiser entender por que algo foi alterado, a menos que você mantenha o código antigo em um comentário.

Se o código for muito complexo para ser entendido sem escrever muitos comentários, sugiro investir sua energia na refatoração para tornar o código legível / sustentável sem muitos comentários.

Afinal, você contrata programadores, não contadores de histórias ;-)