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?
java
c#
programming-practices
code-quality
comments
Diego Alvarez
fonte
fonte
Respostas:
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:
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 histórico é armazenado no controle de origem.
Você também acredita que o comentário foi escrito por essa pessoa.
How
os 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.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.
Todos os autores (além de você) são igualmente credíveis.
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.
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.
Sim. Melhor razão ainda.
Se eu realmente precisar dessas informações, procurarei no controle de origem.
Caso contrário, não é relevante.
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).
fonte
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 ;-)
fonte