Você usa comentários especiais sobre correções de bugs em seu código?

Question

Alguns dos meus colegas usam comentários especiais em suas correções de bugs, por exemplo:

// 2008-09-23 John Doe - bug 12345
// <short description>

Isso faz sentido?
Você comentar correções de bugs de uma maneira especial?

Por favor me avise.

Answer 1

Eu não colocar em comentários como esse, o sistema de controle de origem já mantém que a história e eu já sou capaz de registrar a história de um arquivo.

Eu colocar em comentários que descrevem por que algo não-óbvia está sendo feito embora. Portanto, se a correção de bug torna o código menos previsível e claro, então eu explicar o porquê.

Answer 2

Com o tempo estes podem acumular e adicionar desordem. É melhor para tornar o código claro, adicionar quaisquer comentários para gotchas relacionados que podem não ser óbvio e manter o detalhe bug no sistema de acompanhamento e repositório.

Answer 3

Eu não tendem a comentário na fonte real, porque pode ser difícil manter-se atualizado. No entanto eu colocar ligando comentários no meu log de controle de origem e issue tracker. por exemplo. Eu poderia fazer algo assim no Perforce:

[Bug-Id] Problema com xyz diálogo. código de dimensionamento mudou-se para abc e agora Inicializar mais tarde.

Então, em minha issue tracker vou fazer algo como:

Fixed na lista de alterações 1234.

código de dimensionamento Mudou-se para abc e agora Inicializar mais tarde.

Porque, então, um bom marcador histórico está à esquerda. Também torna mais fácil se você quer saber por que uma determinada linha de código é uma certa maneira, você pode simplesmente olhar para a história arquivo. Depois de encontrar a linha de código, você pode ler o meu comentário cometer e ver claramente que bug que era e como eu fixa-lo.

Answer 4

Só se a solução era particularmente inteligente ou difícil de entender.

Answer 5

Normalmente, eu adicionar o meu nome, meu endereço de e-mail ea data juntamente com uma breve descrição do que eu mudei, isso é porque como consultor muitas vezes eu corrigir o código de outras pessoas.

// Glenn F. Henriksen (<email@company.no) - 2008-09-23
// <Short description>

Dessa forma, os titulares de códigos, ou as pessoas que vem depois de mim, pode descobrir o que aconteceu e eles podem entrar em contato comigo, se eles têm.

(sim, infelizmente, na maioria das vezes eles não têm controle de origem ... para coisas internas eu uso rastreamento TFS)

Answer 6

Embora isso possa parecer uma boa idéia no momento, torna-se rapidamente fora de mão. Tal informação pode ser melhor capturado usando uma boa combinação de sistema de controle de origem e bug tracker. Claro que, se há algo complicado acontecendo, um comentário que descreve a situação seria útil em qualquer caso, mas não a data, nome ou número de bug.

A base de código que estou trabalhando atualmente em no trabalho é algo como 20 anos de idade e eles parecem ter adicionado lotes de comentários como este anos atrás. Felizmente, eles pararam de fazê-lo alguns anos depois de terem convertido tudo para CVS no final dos anos 90. No entanto, tais comentários ainda estão cheios durante todo o código e a política agora é "removê-los se você estiver trabalhando diretamente sobre esse código, mas caso contrário deixá-los". Eles são muitas vezes muito difícil de seguir, especialmente se o mesmo código é adicionado e removido várias vezes (sim, isso acontece). Eles também não contêm a data, mas contêm o número bug que você teria que ir procurar em um sistema arcaico para encontrar a data, para que ninguém faz.

Answer 7

Os comentários como este são porque Subversion permite que você digite uma entrada de registo em cada commit. É onde você deve colocar essas coisas, não no código.

Answer 8

Eu faço-se a correção de bug envolve algo que não é simples, mas mais frequentemente do que não, se o bugfix requer uma longa explicação Eu tomo isso como um sinal de que a correção não foi bem concebido. Ocasionalmente eu tenho que trabalhar em torno de uma interface pública que não pode mudar assim que este tende a ser a fonte desses tipos de comentários, por exemplo:

// <date> [my name] - Bug xxxxx happens when the foo parameter is null, but
// some customers want the behavior.  Jump through some hoops to find a default value.

Em outros casos, o controle de origem cometer mensagem é o que eu uso para anotar a mudança.

Answer 9

Embora eu tendem a ver alguns comentários sobre erros dentro do código de trabalho, a minha preferência pessoal está ligando um código de comprometer-se a um bug. Quando eu digo que eu realmente quero dizer um bug. Depois, você pode sempre olhar para as alterações feitas e saber qual bug estes foram aplicados a.

Answer 10

Esse estilo de comentar é extremamente valioso em um ambiente multi-desenvolvedor, onde há uma gama de habilidades e / ou conhecimento do negócio através dos promotores (por exemplo - em todos os lugares).

Para o desenvolvedor qualificado experiente a razão para uma mudança pode ser óbvio, mas para os desenvolvedores mais recentes que o comentário vai fazê-los pensar duas vezes e fazer mais investigação antes de brincar com ela. Ela também ajuda-los a aprender mais sobre como funciona o sistema.

Oh, e uma nota de experiência sobre a "Acabei de colocar isso no sistema de controle de origem" comentários:

Se não for na fonte, isso não aconteceu.

Eu não posso contar o número de vezes que a história fonte para projetos foi perdido devido à inexperiência com o software de controle de origem, modelos de ramificação impróprios etc. Há apenas um lugar do histórico de alterações não pode ser perdida -. E isso é no arquivo de origem

Normalmente, eu colocá-lo lá em primeiro lugar, em seguida, corte 'n colar o mesmo comentário quando eu check-in.

Answer 11

Não, eu não faço, e eu odeio ter de graffiti como aquele lixo o código. números de bugs pode ser rastreado na mensagem comprometer com o sistema de controle de versão, e por scripts para empurrar relevante cometer mensagens para o sistema de rastreamento de bugs. Eu não acredito que eles pertencem no código fonte, onde futuras edições serão as coisas simplesmente Confuse.

Answer 12

Muitas vezes, um comentário como esse é mais confuso, como você realmente não tem contexto como o que o código original parecia, ou o mau comportamento originais.

Em geral, se a sua correção de bug agora torna o código funcionar corretamente, simplesmente deixá-lo sem comentários. Não há necessidade de comentar código correto.

Às vezes, a correção de bug faz coisas parecer estranho, ou a correção de bug está testando para algo que é fora do comum. Então pode ser apropriado ter um comentário - geralmente o comentário deve remeter para o "número bug" do seu banco de dados de bugs. Por exemplo, você pode ter um comentário que diz "Erro 123 - Conta de comportamento estranho quando o usuário está em 640 por resolução de tela de 480".

Answer 13

Se você adicionar comentários como que depois de alguns anos de manter o código você terá tantos comentários bug correção você não seria capaz de ler o código.

Mas se você mudar algo que olhar direito (mas tem um bug sutil) em algo que é mais complicado é bom para adicionar um breve comentário explicando o que você fez, para que a próxima programador para manter este código não mudá-lo de volta, porque ele (ou ela) pensa que você over-complicou as coisas para nenhuma boa razão.

Answer 14

No. Eu uso subversão e sempre digite uma descrição da minha motivação para cometer uma mudança. Eu normalmente não reafirmar a solução em Inglês, ao invés disso eu resumir as alterações efectuadas.

Eu tenho trabalhado em uma série de projetos, onde eles colocam comentários no código quando correções foram feitas. Curiosamente, e provavelmente não por coincidência, estes eram projectos que ou não utilizar qualquer tipo de ferramenta de controle de origem ou foram mandatados para seguir esta espécie de convenção por decreto da administração.

Honestamente, eu realmente não ver o valor em fazer isso para a maioria das situações. Se eu quero saber o que mudou, eu vou olhar para o registo de subversão e do diff.

Apenas meus dois centavos.

Answer 15

Se o código for corrigido, o comentário é inútil e nunca interessante para ninguém - apenas ruído.

Se o erro não for resolvido, o comentário é errado. Então faz sentido. :) Então, basta deixar esses comentários se você realmente não resolveu o bug.

Answer 16

Para localizar os comentário específico usamos DKBUGBUG - o que significa correção de David Kelley e revisor pode facilmente identidade, Claro, vamos adicionar Data e outra VSTS número de rastreamento de bugs etc junto com este.

Answer 17

Do dados não duplicado meta que o seu VCS vai manter para você. Datas e nomes deve estar na adicionado automaticamente pelo VCS. números de bilhete, nomes gestor / usuário que pediu a mudança, etc deve estar em comentários VCS, não o código.

Ao contrário do que isto:

// $ DATE $ NAME $ TICKET // comentário útil ao próximo pobre alma

Eu faria isso:

// comentário útil ao próximo pobre alma

Answer 18

Se o código está em uma plataforma ao vivo, longe do acesso directo ao repositório de controle de origem, então eu vou adicionar comentários para destacar as alterações feitas como parte da correção para um bug no sistema ao vivo.

Caso contrário, não a mensagem que você entra no check-in deve conter todas as informações que você precisa.

aplausos,

Rob

Answer 19

Quando faço correções de bugs / melhorias em bibliotecas de terceiros / componente muitas vezes eu fazer alguns comentários. Isto torna mais fácil encontrar e mover as alterações, se eu preciso usar uma versão mais recente da biblioteca / componente.

Em meu próprio código I raramente comenta correções.

Answer 20

Eu não trabalho em projetos multi-pessoa, mas às vezes eu adicionar comentários sobre um determinado bug para um teste de unidade.

Lembre-se, não há tal coisa como erros, apenas testes insuficiente.

Answer 21

Uma vez que eu faço tanto TDD possível (tudo o resto é suicídio social, pois todos os outros métodos irá forçá-lo a trabalhar infinitas horas), eu raramente corrigir erros.

Na maioria das vezes eu adicionar observações especiais como este para o código:

// I KNOW this may look strange to you, but I have to use
// this special implementation here - if you don't understand that,
// maybe you are the wrong person for the job.

Parece duro, mas a maioria das pessoas que se chamam de "desenvolvedores" merecem há outras observações.