Existe um ponto para incluir um “log de alterações” em cada arquivo de código quando você está usando o controle de versão?

Eu costumo excluir comentários no código. E por exclusão, quero dizer, com preconceito . A menos que um comentário explique por que uma função específica faz algo, ela desaparece. Tchau tchau. Não passe vai.

Por isso, não deveria surpreendê-lo porque eu também excluiria esses changelogs, pelo mesmo motivo.

O problema com o código comentado e os comentários que são lidos como livros é que você não sabe realmente o quanto é relevante e dá a você um falso entendimento sobre o que o código realmente faz.

Parece que sua equipe não tem boas ferramentas em torno do seu sistema de controle de versão. Como você disse que está usando o Subversion, gostaria de salientar que há muitas ferramentas que ajudarão você a gerenciar seu repositório do subversion. Desde a capacidade de navegar pela sua fonte através da web, até ligar os seus changesets a bugs específicos, você pode fazer muita coisa que mitiga a necessidade destes 'changelogs'.

Eu recebi muitas pessoas comentando e dizendo que talvez eu esteja errado por excluir comentários. A grande maioria do código que eu vi que foi comentado foi um código ruim, e os comentários só têm observado o problema. Na verdade, se algum dia eu comentar 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 não pense que eu digo que os comentários devem ser excluídos em tom de brincadeira, este envio diário da WTF (de um codebase I trabalhei) ilustra perfeitamente o meu ponto:

/// 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 gostaria, exceto que ela ainda está em uso por uma das maiores organizações do governo ao redor.

Esses "logs de alterações" incorporados no código são particularmente imprestáveis. Eles só aparecem como mais uma diferença quando você difere revisões, e uma que você não se importa. Confie no seu VCS - a maioria tem um recurso de "culpa" que mostrará rapidamente quem mudou o quê.

É claro que a coisa realmente horrível era esse recurso dos VCS "antigos", em que você poderia ter o registro real do VCS incorporado nos arquivos de origem. Fusão quase impossível.

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

Não temos comentários incorporados do ChangeLog. Se o fizéssemos, eu os removeria e teria uma "conversa" com a pessoa adicionando-os. Eu acho que eles são indicativos de não entender as ferramentas que você usa, especificamente as vcs.

Nós temos um formato para enviar mensagens que facilita o grep dos logs. Também não permitimos mensagens de commit inúteis ou ambíguas.

Pessoalmente, detesto os registros de alterações no arquivo de código-fonte. Para mim, é como se viesse a violar um princípio de engenharia de software em que qualquer mudança 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 mudanças no software devem ser documentadas quando você verificar o código.

Mas o que eu sei ...

Acho 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 a alterações que afetam a API / interface pulic da classe. Se você está fazendo alterações dentro da classe que não vão quebrar nenhum código que a use, registrar essas alterações em um log de alterações é apenas uma confusão 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 alguma coisa 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 faz principalmente coisas sobre o C #, e sempre usamos comentários XML embutidos para documentar nossa API, então a leitura de documentação sobre alterações de API públicas é mais ou menos tão simples quanto a utilização do intellisense.

Eu acho que insistir em um log de alterações dentro do arquivo de origem está apenas adicionando fricção desnecessária à máquina e acaba com 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 que tinha 17 anos de história, desenvolvimento e atualizações anuais por trás dele. Nem todas as migrações de um sistema de controle de versão para o seguinte preservariam comentários ou notas de check-in. Nem todos os desenvolvedores ao longo desses anos mantiveram qualquer consistência com os comentários / notas de check-in.

Com comentários no código-fonte, o histórico arqueológico das alterações foi mantido como notas, e não como um código comentado. E, sim, eles ainda estão enviando o código VB6.

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

Se a sua equipe não estiver adicionando comentários no check-in ou estiver 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 só isso, mas espera-se que cada cheque seja anexado a um ingresso em Jira. Quando você procurar no Jira no futuro, poderá ver todos os arquivos que foram verificados e quando o problema ocorreu junto com o comentário deixado. É bem prático.

Basicamente, o controle de versão é apenas uma ferramenta, é como sua equipe usa essa ferramenta que fornecerá as vantagens que você está procurando. Todos na equipe precisam concordar com a forma como eles serão usados para fornecer o melhor rastreamento de correção de erros, além de limpar as revisões de código.

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

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

Eu guardo (quase) com o 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ê tem a necessidade de ter muitos comentários em seu código, isso é um cheiro próprio e grita "refactor me!".

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

Nosso antigo código do PowerBuilder ainda os utiliza, mas acho que isso é apenas um fator de conforto para certas pessoas. Isso também é compilado para distribuição, então (IMO eles deveriam) usar a história do VCS.

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

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

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

Agora, se todos os desenvolvedores verificassem 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 apenas mudaria a validação sem pesquisar o histórico de quem a adicionava e por quê - e do ponto de vista tecnológico - um sistema de controle de versão teria dificuldade em rastrear o mesmo "linha de código se passou de uma linha para outra ou foi refatorada em uma classe diferente. É muito mais provável que os comentários no código sejam vistos e, mais importante, que um desenvolvedor subseqüente perceba que uma mudança aparentemente simples pode não ser tão simples.

Dito isso, os comentários do log de alterações no código devem ser relativamente raros. Eu não estou defendendo que os comentários do log de alterações sejam adicionados toda vez que um código for refatorado ou quando um erro verdadeiro for corrigido. Mas se o requisito original for "Foo é opcional" e alguém aparecer e alterar o requisito para "Foo é necessário para suportar a barra de processo de recebimento de dados", isso é algo que eu consideraria a inclusão de um comentário. Porque há uma strong possibilidade de que algum futuro usuário / analista desconheça o processo da barra de recebimento de dados e desconheça o motivo pelo qual o Foo foi necessário e peça para tornar o Foo opcional novamente e causar dores de cabeça no processo do Bar.

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

Estou surpreso de ver que ninguém mencionou isso, mas a razão original para isso não está em conformidade com 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?

A razão pela qual continuamos a manter um registro de alterações em nossa seção de comentários é para facilitar o uso. Muitas vezes, ao depurar um problema, é mais fácil rolar para o topo do arquivo e ler o log de alterações do que abrir o arquivo de controle de origem, localizar o arquivo dentro dele e localizar as alterações feitas