Manutenção de código: para adicionar comentários no código ou apenas deixá-lo no controle de versão?

Foi-nos pedido que adicionássemos comentários com as tags de início, fim, descrição, solução, etc., para cada alteração que fizermos no código como parte da correção de um bug / implementação de um CR.

Minha preocupação é: isso oferece algum valor agregado? No momento, temos todos os detalhes no histórico de controle de versão, o que nos ajudará a rastrear todas as alterações?

Mas meus líderes estão insistindo em ter os comentários como uma "boa" prática de programação. Um dos argumentos deles é que, quando um CR precisa ser desmarcado / alterado, seria complicado se não houvesse comentários.

Considerando que as alterações estariam amplamente entre o código, seria realmente útil adicionar comentários para cada alteração que fizermos? Não devemos deixar isso para o controle de versão?

Você está absolutamente certo. O rastreamento de alterações é o trabalho do seu sistema de controle de versão. Toda vez que você efetua um commit, você deve escrever uma mensagem de commit explicando o que foi feito e referenciar seu sistema de rastreamento de erros, se for uma correção. Colocando um comentário no código dizendo

// begin fix for bug XXXXX on 10/9/2012
...
// end fix for bug XXXXX

toda vez que você corrige um erro, seu código fica rapidamente ilegível e impossível de manter. Isso também resultará na duplicação da mesma informação em dois locais, o que tornará a bagunça ainda pior.

Os comentários não devem ser usados ​​para rastrear erros e também não devem descrever o que seu código está fazendo. Eles devem explicar por que você está fazendo X ou por que está fazendo X dessa maneira específica. Se você sentir necessidade de escrever um comentário explicando o que um bloco de código está fazendo, é um cheiro de código que indica que você deve refatorar esse bloco em uma função com um nome descritivo.

Então, ao invés de

// fixed bug XXXXX on 10/9/2012

você pode ter um comentário que diz

// doing X, because otherwise Y will break.

ou

// doing X, because doing Y is 10 times slower.

Use a melhor ferramenta para o trabalho. Seu sistema de controle de versão deve ser a melhor ferramenta para gravar quando são feitas correções de erros e CRs: registra automaticamente a data e quem fez a alteração; nunca esquece de adicionar uma mensagem (se você a configurou para exigir mensagens de confirmação); nunca anota a linha de código incorreta ou exclui acidentalmente um comentário. E se o seu sistema de controle de versão já está fazendo um trabalho melhor que os seus comentários, é tolice duplicar o trabalho adicionando comentários.

A legibilidade do código fonte é fundamental. Uma base de código cheia de comentários, fornecendo o histórico completo de todas as correções de erros e CR feitas, não será muito legível.

Mas não pule os comentários completamente: bons comentários (sem documentar servilmente cada inicialização / parada / descrição / solução de cada bugfix e CR) aumentam a legibilidade do código. Por exemplo, para um código complicado ou pouco claro que você adiciona para corrigir um bug, // fix ISSUE#413é um excelente comentário um comentário do formulário informando às pessoas onde encontrar mais informações no rastreador de problemas.

Comentários no código são sobre o que o código é naquele momento. Tirar um instantâneo a qualquer momento não deve se referir a versões antigas (ou pior, futuras) do código.

Os comentários no VCS são sobre como o código foi alterado. Eles devem ler como uma história sobre desenvolvimento.

Agora, toda mudança deve incluir comentários? na maioria dos casos, sim. A única exceção que imagino é quando o comportamento esperado já foi documentado, mas não foi o que você recebeu, por causa de um bug. A correção torna os comentários existentes mais precisos, para que eles não precisem ser alterados. O bug em si deve ser documentado no histórico do ticket e no comentário de confirmação, mas somente no código se o código parecer estranho. Nesse caso, a // make sure <bad thing> doesn't happendeve ser suficiente.

Um tipo de comentário que eu realmente aprecio é:

// Implementado para a regra de negócios 5 da proposta 2

ou o que diabos você usa para reunir seus requisitos.

Isso tem duas vantagens, uma é que permite encontrar o motivo pelo qual você implementou um determinado algoritmo sem pesquisar e outro é que o ajudará a se comunicar com engenheiros que não são de software que trabalham / criam os documentos de requisitos.

Isso pode não ajudar em equipes menores, mas se você tiver analistas que desenvolvem seus requisitos, pode ser inestimável.

Seus leads estão certos quando dizem que os comentários são uma boa prática de programação, no entanto, há exceções. Adicionar um comentário para cada alteração que você fizer é um deles. E você está certo ao dizer que isso deve pertencer ao sistema de controle de versão. Se você precisar manter esses comentários em um único local, o VCS é o caminho a seguir. Os comentários no código-fonte tendem a envelhecer e não se manter. Nenhum comentário é muito melhor que um comentário ruim. O que você não quer é ter comentários nos dois lugares (no código e no VCS) que estão fora de sincronia. O objetivo é manter as coisas secas, tendo uma única fonte de verdade para alterações no código.

Além do que os outros disseram, considere o que acontece se uma mudança tiver efeitos colaterais em todo o sistema. Digamos que você refatorar parte de uma interface principal no processo de implementação de uma solicitação de mudança - esse tipo de mudança pode facilmente tocar uma grande porcentagem dos arquivos de código-fonte em qualquer software não trivial com o que equivale a mudanças triviais (classe ou nome do método é alterado). Você deveria passar por todos os arquivos tocados por essa operação para anotá-lo manualmente com esses comentários, em vez de confiar no VCS fazendo tudo automaticamente? Em um caso, você está procurando pouco mais de um trabalho de cinco minutos com qualquer ferramenta de refatoração decente, seguida de uma recompilação para garantir que nada interrompa a construção, enquanto o outro pode facilmente se transformar em um dia de trabalho. Para que benefício específico?

Considere também o que acontece quando você move partes do código. Um dos desenvolvedores de banco de dados com quem trabalho está em grande parte "cada linha do SQL deve ser anotada com a revisão em que foi alterada, e faremos históricos de revisão separados para cada arquivo, porque é mais fácil ver quem mudou o que quando e por que ". Isso funciona meio que bem quando a mudança éna ordem de alterar linhas simples. Não funciona tão bem quando, como fiz recentemente para corrigir um problema sério de desempenho, você interrompe partes de uma consulta maior introduzindo tabelas temporárias e altera a ordem de algumas das consultas para melhor se adequar ao novo fluxo de código. É verdade que a diferença em relação à versão anterior era praticamente sem sentido, pois dizia que cerca de dois terços do arquivo havia sido alterado, mas o comentário do check-in também era algo como "grande reorganização para corrigir problemas de desempenho". No momento em que você olhou manualmente para as duas versões, ficou bastante claro que grandes partes eram realmente iguais, apenas se movimentavam. (E o procedimento armazenado em questão demorou regularmente mais de meio minuto para ser executado, por alguns segundos. Nesse momento,

Com muito poucas exceções, o rastreamento de alterações e a referência de problemas são o trabalho do VCS, IMNSHO.

Eu normalmente sigo esta regra: se a mudança é óbvia e o código resultante não levanta perguntas, não reverte ou altera substancialmente qualquer comportamento anterior de maneira substancial - deixe para o VCS rastrear números de bugs e outras informações de mudança.

No entanto, se houver uma mudança que não seja óbvia, que mude a lógica - especialmente substancialmente a lógica feita por outra pessoa de uma maneira não óbvia - pode ser muito benéfico adicionar algo como "essa mudança é fazer isso e isso por causa do bug # 42742 ". Dessa forma, quando alguém olha o código e se pergunta "por que isso está aqui? Isso parece estranho", ele tem alguma orientação bem à sua frente e não precisa investigar via VCS. Isso também evita situações em que as pessoas quebram as alterações de outras pessoas porque estão familiarizadas com o antigo estado do código, mas não percebem que ele foi alterado desde então.

Comentários relacionados ao controle de versão não pertencem ao arquivo de origem. Eles apenas adicionam desordem. Como é provável que eles sejam colocados no mesmo local (como um bloco de comentários na parte superior do arquivo), eles causarão conflitos de incômodo somente para comentários quando mesclas de ramos paralelos.

Qualquer informação de rastreamento que possa ser retirada do controle de versão não deve ser duplicada no corpo do código. Isso vale para idéias tolas, como as palavras-chave de checkout do RCS, como $Log$e seu tipo.

Se o código sair do escopo do sistema de controle de versão, essa trilha de comentários sobre seu histórico perde o contexto e, portanto, a maior parte do seu valor. Para entender corretamente a descrição da mudança, precisamos acessar a revisão, para que possamos ver o diff da versão anterior.

Alguns arquivos antigos no kernel do Linux têm grandes blocos de comentários no histórico. Eles datam de quando não havia sistema de controle de versão, apenas tarballs e patches.

Os comentários no código devem ser mínimos e precisos. A adição de informações sobre defeitos / alterações não é valiosa. Você deve usar o controle de versão para isso. Algum tempo, o controle de versão fornece uma maneira um pouco melhor de alterar: usamos o ClearCase UCM; As atividades do UCM são criadas com base nos números de defeitos, na área de alteração etc. (por exemplo, defect29844_change_sql_to_handle_null).

Comentários detalhados são preferidos nos comentários de check-in.

Prefiro incluir detalhes sobre informações de base, detalhes da solução NÃO implementada devido a alguns efeitos colaterais.

Pramagic Programmer e CleanCode levam às seguintes diretrizes

Mantenha o conhecimento de baixo nível no código, onde pertence, e reserve os comentários para outras explicações de alto nível.