Gerenciamento de Configuração - História no Código Comentários

Question

Deixe-me colocar um pouco de informação antes de pedir a minha pergunta:

I recentemente se juntou a um novo grupo de desenvolvimento de software que utiliza ferramentas Rational para gerenciamento de configuração, incluindo um controle de fonte e sistema de gestão da mudança. Além dessas ferramentas, a equipe tem uma prática padrão de notar qualquer alteração de código como um comentário no código, tais como:

///<history>
   [mt] 3/15/2009  Made abc changes to fix xyz
///</history>

Seu objetivo oficial para o padrão comentando é que "os comentários fornecem rastreabilidade da exigência de modificação do código".

Estou me preparando para representar um argumento que esta prática é desnecessária e redundante; que a equipe deve se livrar desta norma imediatamente.

A saber - o sistema de gestão da mudança é o lugar para construir a rastreabilidade do requisito de modificação do código, e controle de origem pode fornecer história detalhada de mudanças através da realização de um Diff entre as versões. Quando o código-fonte é o check-in, o bilhete de gerenciamento de mudança correspondente é anotado. Quando um bilhete CM for resolvido, notamos que arquivos de código-fonte foram modificados. Eu acredito que isto proporciona uma referência cruzada suficiente para a rastreabilidade desejado.

Gostaria de saber se discorda qualquer pessoa com o meu argumento. Estou faltando algum benefício da história código fonte comentou que o gerenciamento de mudanças e sistemas de controle de origem não pode fornecer?

Answer 1

Para mim, eu sempre achei tais comentários a ser mais problemas do que eles valem: eles podem causar conflitos de mesclagem, pode aparecer como 'falsos positivos' quando você está tentando isolar os diffs entre duas versões, e pode alterações de código de referência que desde então ficou obsoleto com alterações posteriores.

É muitas vezes (nem sempre, mas muitas vezes) possível sistemas versão de controle de mudanças, sem perder de metadados. Se você tivesse que mover o código para um sistema que não apoiar esta, não seria difícil escrever um script para converter o histórico de alterações para comentários antes da transição.

Answer 2

Um comentário permite que você encontre todas as mudanças e as suas razões no direito código onde eles são relevantes sem ter que cavar diffs e complexidades do sistema de controle de versão. Além disso, você deve decidir a mudança de sistema de controle de versão, os comentários vão ficar.

Eu trabalhei em um projeto grande com a prática similar que tinha mudado de sistema de controle de origem duas vezes. Não havia um dia em que eu não estava feliz por ter esses comentários.

É redundante? Sim. É desnecessário? Não.

Answer 3

Eu sempre pensei que o código deve ser, é claro, sob controle de versão, e que o código fonte de corrente (aquele que você pode abrir e ler hoje) deve ser válido apenas no tempo presente .

Não importa se um relatório pode ter até 3 eixos no mês passado e última vez que você atualizou para suportar até 6 eixos. Não importa se você expandiu alguma função ou fixo algum erro, enquanto a versão atual pode ser facilmente compreendido. Quando você corrigir um erro, basta deixar o código fixo.

Há uma exceção, no entanto. Se (e somente se) os olhares de código fixos menos intuitivos para você do que a anterior, incorreto; se você sentir que alguém pode vir amanhã e, apenas lendo o código, ser tentado a mudar de volta para o que "parece mais correto" , então é bom para adicionar um comentário: "Isto é feito este maneira de blah evitar ... blá, blá. " Além disso, se o problema por trás é uma história de guerra infame dentro da cultura da equipe, ou se por algum motivo o banco de dados relatório de erro contém informações muito interessantes sobre esta parte do código , eu não iria encontrá-lo incorreta para adicionar "(veja Bug Id 10005)" para o comentário explicando.

Answer 4

O que salta à mente para mim é fornecedor lockin. Se você nunca se afastou da Rational, você precisa ter certeza de que a história completa mudança foi mantida durante a migração -. Não apenas a versão dos artefatos

Answer 5

Quando você está no código que você precisa saber por que ele está estruturado como esse, daí em código comentando. Ferramentas que sentar-se fora do código, bom, embora possam ser, exigem demais de uma mudança de contexto no seu cérebro para ser útil. Bem como que, tentando fazer engenharia reversa do código intenção de documentação e um diff é muito muito difícil, eu prefiro ler uma linha de comentário em qualquer dia.

Answer 6

Houve uma fase no trabalho de código I on, de volta ao quadro 1994-1996 tempo, onde havia uma tendência para inserir comentários do histórico de alterações no topo do arquivo. Esses comentários estão agora sem sentido e inútil, e uma das muitas limpezas padrão I realizam ao editar arquivos contendo tais comentários é para removê-los.

Por outro lado, há também alguns comentários com um número de bug no local onde a alteração é feita, geralmente explicando por que o código ridículo é como ela é. Estes podem ser muito úteis. O número bug dá-lhe algum outro lugar para olhar para obter informações, e os dedos o culpado. (Ou vítima - isso varia)

Por outro lado, itens como este - genuína; limparam na semana passada -. me faz cerrar os dentes

    if (ctab->tarray && ctab->tarray[i])
#ifndef NT
      prt_theargs(*(ctab->tarray[i]));
#else
      /* Correct the parameter type mismatch in the line above */
      prt_theargs(ctab->tarray[i]);
#endif /* NT */

A equipa NT recebi a ligação correta; porque eles pensaram que era uma correção específica da plataforma está além de mim. Claro que, se o código tinha usado protótipos em vez de declarações apenas sem parâmetros antes de agora, então a equipe Unix teria que corrigir o código também. O comentário foi uma ajuda - assegurando-me de que o bug foi genuína -. Mas exasperante