É uma boa prática comentar com o número da edição?

Eu vi muitos números de problemas de comentários do código jQuery . (Na verdade, havia 69 números de problemas no código jQuery.) Acho que seria uma boa prática, mas nunca vi nenhuma orientação.

Se for uma boa prática, quais são as diretrizes para essa prática?

Em geral, eu não consideraria isso uma boa prática. Mas, em casos excepcionais, pode ser muito útil, ou seja, quando o código precisa fazer algo não intuitivo para corrigir um problema complexo e, sem qualquer explicação, haveria o risco de alguém querer "consertar" esse código estranho e, assim, quebrá-lo. , ao explicar o raciocínio resultaria em um grande comentário que duplica as informações do problema.

Acho que basta adicionar o número do problema à mensagem de confirmação quando você confirma a correção relacionada ao seu sistema de controle de origem.

Por exemplo:

Bug # 203: As conexões com o banco de dados não atingem o tempo limite após 30 segundos.

Acho que adicionar números de problemas, nomes de desenvolvedores ou datas em que as alterações foram feitas no código apenas polui a base de código e deve realmente ser gerenciado externamente pelo seu sistema de controle de origem.

Eu discordo completamente dos outros pôsteres aqui!

Comentários de código com referências de rastreamento podem ser uma grande ajuda para a programação de manutenção.

Se estou rastreando um bug e me aproximando da área do código, ver que ele foi alterado recentemente e ter um link para o contexto da alteração é um envio divino.

Sim, temos controle de código-fonte, mas pode ser bastante lento verificar arquivos e módulos individualmente. Você deseja que essas coisas surjam com você nas alterações recentes.

Eu provavelmente os reprovaria, pois vejo os realmente antigos na base de código, mas há muito pouco lado negativo em manter os mais recentes e muito tempo potencialmente economizado para desenvolvedores, se você os usar com inteligência.

Na verdade, acho que essas pequenas referências ao seu sistema de rastreamento de bugs são preferíveis a comentários detalhados no código.

Se você se inscrever em uma política de "Código Limpo", provavelmente precisará se perguntar se é uma boa prática adicionar comentários. Se o código puder ser esclarecido apenas com um comentário, adicione um, com certeza, caso contrário, você poderá entender facilmente o que o seu código faz simplesmente lendo-o (desde que você esteja usando nomes sensíveis para suas variáveis, métodos etc.).

Independentemente de sua visão pessoal sobre se comentar é uma boa prática ou não, um comentário deve conter informações de valor direto para o código ao qual o comentário está se referindo. Nesse caso, a questão é se adicionar um número de problema agrega valor ao código. O problema que vejo ao adicionar o número do problema é que você pode ter uma seção de código que pode ser modificada fortemente para satisfazer vários problemas e, depois de um tempo, pode ser impossível identificar corretamente quais alterações estão relacionadas a um problema específico. Problemas subsequentes, por exemplo, podem exigir que o código relacionado a problemas anteriores seja fortemente refatorado. Este é talvez um exemplo extremo, no entanto, mostra como os números dos problemas nos comentários no código podem ser bastante inúteis.

Se você pudesse garantir que a situação que acabei de descrever nunca aconteceria, ainda argumentaria que o número do problema em si ainda é bastante inútil sem uma descrição do que é o problema e, no entanto, todas essas informações realmente pertencem ao seu sistema de rastreamento de problemas e deve ser duplicado. Um lugar melhor para anotar o número do problema seria no seu sistema de controle de versão como um comentário de confirmação. A vantagem é que você pode comparar versões e ver as alterações de código relacionadas a um problema específico, enquanto o próprio número do problema fornece o identificador necessário, se você deseja revisar o motivo da alteração no código.

Com tudo isso em mente, sugiro que não seja realmente uma boa prática, como adicionar números de problemas a comentários no seu código.

Eu acho que é uma boa prática se referir a uma questão para uma leitura mais aprofundada, dando uma breve explicação no próprio comentário.

Geralmente, apenas adiciono comentários se houver algo sutil ou pouco intuitivo nesse trecho de código. Como algumas questões sutis não podem ser explicadas completamente em poucas linhas, e não quero adicionar dezenas de linhas de comentários, adicione um breve comentário descrevendo o que isso está tentando alcançar e consulte o problema para detalhes.

Por exemplo:

// Verify MAC before checking the padding, to avoid padding oracle attacks
// See issue 123 for details

Onde o problema 123 descreve como esse ataque pode ser e por que o novo código é imune ao ataque.

Ou:

// Using foo's algorithm here, since it fits out usage pattern best
// Check issue 345 for a discussion of possible algorithms, and why foo was chosen.

O principal problema com a inserção de números de problemas em sua fonte é que agora você tem uma referência externa. Portanto, você precisa ter certeza de que não perderá o problema.

A inclusão do número do problema nas mensagens de confirmação pode ser muito útil quando o código-fonte é conectado com integração contínua. Aplicativos como o TeamCity extraem essas informações e permitem melhores relatórios.

Com o exposto acima, não tenho 100% de certeza de que recebe dos comentários do código. A inclusão de números de problemas no código funciona bem se os números de problemas persistirem (por exemplo, você não altera os rastreadores de problemas) e você não tem muitos problemas para um determinado projeto.

Provavelmente é mais útil se você descrever o problema e a solução para que o próximo desenvolvedor não precise procurar o número do problema. O compilador ou o minificador apenas removerão seus comentários antes que o código seja lançado na natureza, para que não haja impacto no resultado final.