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?
fonte
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.fonte
fix ISSUE#413
não é um bom comentário no código. Você deve entender o código sem precisar consultar a documentação externa. Em vez de fornecer um número aleatório, explique por que essa parte complicada do código é necessária para fazer o que. É para isso que servem os comentários: Explicar as partes do código que não são óbvias.fix ISSUE#413
é onde o problema é tão complicado (um caso de canto extremamente dependente do sistema operacional e da configuração, ou apenas acionado por dados ruins de clientes em particular) que descrevê-lo adequadamente seria necessário. alguns parágrafos; esse tipo de coisa é mais bem tratado por um rastreador de problemas, a IMO. Mesmo assim, algum tipo de breve descrição é boa.fix ISSUE#413
é perfeitamente bom e até preferível, desde que também forneça uma quantidade razoável de informações sobre qual é o problema # 413. Apenas resumir o relatório do problema sem fornecer um indicador para ele torna a vida mais difícil para um futuro leitor que precise de todos os detalhes.fix ISSUE#413
um comentário para completar, mas não o use como muleta.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 happen
deve ser suficiente.fonte
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.
fonte
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.
fonte
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.
fonte
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.
fonte
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.
fonte
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.
fonte