Existe um ponto em incluir um "log de alterações" em cada arquivo de código quando você estiver usando o controle de versão?

Fiquei com a impressão de que um sistema de controle de versão eliminava a necessidade de "registros de alterações" colados em todo o código. Eu sempre vi o uso continuado de logs de alterações, incluindo grandes blocos longos no início dos procedimentos armazenados, com uma grande seção bloqueada para alterações no arquivo e espalhando o código por coisas como:

// 2011-06-14 (John Smith) Change XYZ to ABC to fix Bug #999

e:

// 2009-95-12 (Bob Jones) Extracted this code to Class Foo 
// <commented-out code here>

A razão para isso, como me foi explicado, é que leva muito tempo para examinar nossos logs do VCS, tentando descobrir quem mudou o quê e por quê, enquanto o possui no próprio arquivo de código, na parte superior ou próxima da respectiva. mudar, facilita ver quem mudou o que e quando. Enquanto eu vejo o ponto disso, parece redundante e meio que cheira a "Eh, nós realmente não entendemos como usar nossos VCS corretamente, então não vamos nos preocupar com essas coisas".

O que você acha? Você usa os comentários e o log? Apenas o log? Você acha que é mais fácil codificar quando você vê acima de um bloco de código que John Smith alterou o método para verificar o XYZ uma semana atrás, em vez de precisar pesquisar os logs e comparar os arquivos de código em uma ferramenta Diff?

EDIT: Usando SVN, mas basicamente apenas como um repositório. Sem ramificações, sem mesclagens, nada, exceto log + armazenamento.

Costumo excluir comentários no código. E com exclusão, quero dizer, com preconceito . A menos que um comentário explica por que uma determinada função faz algo, ele vai embora. Tchau tchau. Não passe vai.

Portanto, não deveria surpreender que eu também excluísse esses registros de alterações pela mesma razão.

O problema com o código comentado e os comentários que parecem livros é que você realmente não sabe o quanto é relevante e fornece uma falsa sensação de entendimento sobre o que o código realmente faz.

Parece que sua equipe não possui boas ferramentas no sistema de controle de versão. Como você disse que está usando o Subversion, gostaria de salientar que existem muitas ferramentas que ajudarão você a gerenciar seu repositório do subversion. Desde a capacidade de navegar em sua fonte pela Web, até vincular seus conjuntos de alterações a erros específicos, você pode fazer muito que atenua a necessidade desses 'registros de alterações'.

Muitas pessoas comentam e dizem que talvez eu esteja errado ao excluir comentários. A grande maioria do código que vi que foi comentado tem código ruim e os comentários apenas obscureceram o problema. De fato, se eu comentar algum código, você pode ter certeza de que estou pedindo perdão ao programador de manutenção, porque estou relativamente certo de que eles vão querer me matar.

Mas, para que você não pense que os comentários devem ser excluídos em tom de brincadeira, essa submissão diária do WTF (de uma base de código em que trabalhei) ilustra perfeitamente meu argumento:

/// The GaidenCommand is a specialized Command for use by the
/// CommandManager.
///
/// Note, the word "gaiden" is Japanese and means "side story",
/// see "http://en.wikipedia.org/wiki/Gaiden".
/// Why did I call this "GaidenCommand"? Because it's very similar to
/// a regular Command, but it serves the CommandManager in a different
/// way, and it is not the same as a regular "Command". Also
/// "CommandManagerCommand" is far too long to write. I also toyed with
/// calling this the "AlephCommand", Aleph being a silent Hebrew
/// letter, but Gaiden sounded better.

Ah ... As histórias que eu poderia contar sobre essa base de código, e eu contaria, exceto que ainda está em uso por uma das maiores organizações governamentais ao redor.

Os "registros de alterações" incorporados no código são particularmente insignificantes. Eles apenas aparecem como outra diferença quando você faz uma revisão diferente e com a qual você realmente não se importa. Confie no seu VCS - a maioria tem um recurso de "culpa" que mostra muito rapidamente quem mudou o quê.

É claro que o mais horrível era esse recurso dos VCS "antigos", nos quais você podia ter o registro VCS real incorporado nos arquivos de origem. Tornou a fusão quase impossível.

Eu tenho um único arquivo ChangeLog para cada projeto que é preenchido automaticamente por determinadas mensagens de confirmação.

Não temos comentários incorporados do ChangeLog. Se o fizéssemos, eu os removia e conversava com a pessoa que os adicionava. Eu acho que eles são indicativos de não entender as ferramentas que você usa, especificamente os vcs.

Temos um formato para enviar mensagens que facilita o recebimento dos logs. Também proibimos mensagens de confirmação inúteis ou ambíguas.

Pessoalmente, detesto logs de alterações no arquivo de código-fonte. Para mim, parece que viola um princípio de engenharia de software, pois qualquer alteração que eu faça deve ser feita em vários lugares. Muitas vezes, as informações do log de alterações são completamente inúteis e sem importância. Na minha humilde opinião, as alterações no software devem ser documentadas quando você faz o check-in do código.

Mas o que eu sei ...

Penso que, se houver uma insistência na implementação da prática de manter um log de alterações dentro do código-fonte, o log de alterações deve ser limitado às alterações que afetam a API / interface pulic da classe. Se você estiver fazendo alterações dentro da classe que não quebrará nenhum código que o utilize, registrar essas alterações em um log de alterações é apenas uma bagunça na minha opinião. No entanto, posso ver como às vezes pode ser útil verificar a parte superior do arquivo de código-fonte para obter documentação sobre quaisquer alterações que possam ter quebrado algo para qualquer outra pessoa. Apenas um resumo de como a alteração pode afetar a API e por que a alteração foi feita.

Por outro lado, minha loja trabalha principalmente com C #, e sempre usamos comentários XML embutidos para documentar nossa API, portanto, ler a documentação sobre alterações de API pública é mais ou menos tão simples quanto utilizar o intellisense.

Penso que insistir em um log de alterações no arquivo de origem está apenas adicionando atrito desnecessário à máquina e derrota um dos propósitos de implementar um sistema de controle de versão em primeiro lugar.

A última empresa em que trabalhei tinha um software com 17 anos de história, desenvolvimento e atualizações anuais por trás. Nem todas as migrações de um sistema de controle de versão para o outro preservariam comentários ou notas de check-in. Nem todos os desenvolvedores ao longo desses anos mantiveram consistência com os comentários / notas do check-in.

Com comentários no código fonte, a história arqueológica das alterações foi mantida como anotação, não como comentário. E, sim, eles ainda estão enviando código VB6.

O controle de versão pode substituir os comentários do log de alterações no código se os desenvolvedores da sua equipe o estiverem usando corretamente.

Se sua equipe não estiver adicionando comentários no check-in ou deixando comentários inúteis, será muito difícil encontrar as informações que você está procurando no futuro.

Na minha empresa atual, somos obrigados a enviar um comentário a cada check-in. Não apenas isso, mas devemos anexar cada check-in com um bilhete em Jira. Quando você procurar no Jira no futuro, poderá ver todos os arquivos que foram registrados e quando, para esse problema, junto com o comentário que foi deixado. É bem útil.

Basicamente, o controle de versão é apenas uma ferramenta, é como sua equipe usa essa ferramenta que fornecerá as vantagens que você procura. Todos na equipe precisam concordar com a forma como o usarão para melhor fornecer o rastreamento de correções de erros, bem como revisões de código limpas.

Isso é uma sobra dos dias em que os logs VCS eram confusos e os sistemas VCS eram difíceis de manusear (lembro-me daqueles dias, em algum lugar no final dos anos 80).

Sua suspeita é totalmente correta, esses comentários são mais um obstáculo do que uma ajuda e qualquer VCS moderno permitirá que você encontre exatamente o que está procurando. Obviamente, você (e seus colegas) terão que gastar aprox. 30 a 60 minutos aprendendo a dirigir todos esses recursos (o que, suspeito, é realmente a razão pela qual esses comentários ainda estão lá).

Eu mantenho (quase) com George. Os comentários no código só são realmente justificados se explicarem algo que não é imediatamente visível no próprio código. E isso acontece apenas raramente em bom código. Se você precisa ter muitos comentários em seu código, isso é um cheiro próprio e grita "refatore-me!".

Ainda os incluímos na origem do procedimento armazenado, porque é assim que podemos saber exatamente qual versão existe no cliente. O restante do aplicativo é distribuído compilado, portanto, temos números de versão do módulo que vinculam de volta à origem, mas os SPs são distribuídos como origem aos clientes para compilação local no banco de dados.

Nosso código legado do PowerBuilder ainda os usa, mas acho que isso é apenas um fator de conforto para certas espreitadelas. Isso também é compilado para distribuição, então (IMO, eles devem) usar o histórico de VCS.

Se você estiver usando SVN, isso é uma perda de tempo e totalmente inútil.

SVN tem a função de culpa. Isso informará exatamente quem criou todas as linhas em um determinado arquivo e quando.

Os comentários do log de alterações são excepcionalmente úteis no código quando ajudam um desenvolvedor subsequente a fazer melhores perguntas sobre novos requisitos. Quando um desenvolvedor vê um comentário, por exemplo, de que Fred criou o campo Foo necessário há 6 meses para atender a algum requisito, esse desenvolvedor sabe que precisa fazer alguma pergunta antes de implementar a solicitação mais recente para tornar o Foo opcional. Quando você lida com sistemas complexos, é provável que diferentes partes interessadas tenham prioridades e desejos diferentes. Os comentários do log de alterações podem ser muito úteis para documentar quais dessas trocas foram feitas para evitar problemas no futuro.

Agora, se todo desenvolvedor verificasse o histórico completo de cada linha de código antes de fazer qualquer alteração, ter esses comentários no código seria redundante. Mas isso é muito irrealista, tanto do ponto de vista do fluxo de trabalho - a maioria dos desenvolvedores mudaria a validação sem pesquisar a história de quem a adicionou e por que - e do ponto de vista da tecnologia - um sistema de controle de versão teria dificuldade em rastrear o "mesmo "linha de código se foi movida de uma linha para outra ou foi refatorada para uma classe diferente. Os comentários no código são muito mais prováveis ​​de serem vistos e, mais importante, levam um desenvolvedor subseqüente a observar que uma mudança aparentemente simples pode não ser tão simples.

Dito isto, os comentários do log de alterações no código devem ser relativamente raros. Não estou defendendo que os comentários do log de alterações sejam adicionados toda vez que um pouco de código for refatorado ou quando um bug verdadeiro for corrigido. Mas se o requisito original era "Foo é opcional" e alguém aparece e altera o requisito para "Foo é necessário para dar suporte à barra de processo downstream", é algo que eu consideraria fortemente adicionar um comentário. Porque existe uma forte possibilidade de que algum usuário / analista futuro desconheça o processo Bar a jusante e não saiba o motivo pelo qual o Foo foi requerido e peça para torná-lo opcional novamente e causar dores de cabeça no processo Bar.

E isso é antes de considerar que as organizações podem decidir mudar seu sistema de controle de versão com alguma frequência, principalmente à medida que crescem de pequenas empresas com um punhado de desenvolvedores para empresas muito maiores. Essas migrações geralmente resultam na perda de comentários no log de alterações - apenas os comentários no código são preservados.

Estou surpreso ao ver que ninguém mencionou isso, mas não é o motivo original para cumprir os requisitos de licença? Ou seja, algumas licenças dizem que qualquer alteração feita no arquivo deve ser anotada no próprio arquivo?

O motivo pelo qual continuamos mantendo um log de alterações em nossa seção de comentários é a facilidade de uso. Geralmente, ao depurar um problema, é mais fácil rolar para a parte superior do arquivo e ler o log de alterações do que abrir o arquivo de controle de origem, localizar o arquivo nele e encontrar as alterações feitas.