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?

75

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.

Wayne Molina
fonte
4
Qual sistema de controle de versão você está usando?
ChrisF
11
Algumas lojas usavam registros de alterações antes de existirem sistemas de controle de origem. A inércia e a familiaridade mantêm os registros de alterações.
Gilbert Le Blanc
2
+1 - Minha equipe também faz isso, e tentei convencer alguns deles de que é o papel do VCS. O problema começa quando esses comentários não são atualizados com o código real ... E o pior é que o gerenciamento decidiu adicionar registros de alterações a todos os métodos também.
slaphappy
2
+1 - Eu luto com nosso desenvolvedor sênior há quase dois anos sobre isso. Sua única justificativa para adicionar esses comentários inúteis é que facilita um pouco a fusão das alterações nos métodos de 3000 linhas. A idéia de que um método de 3000 linhas é obsceno é recebida com desprezo.
21711 Joshua Smith
1
Se "demorar muito para examinar os [seus] registros do VCS", você está fazendo algo errado.
perfil completo de Keith Thompson

Respostas:

46

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.

George Stocker
fonte
4
Sempre que luto com uma parte específica da lógica complexa, os comentários às vezes podem me ajudar a contextualizar por que a lógica é tão complicada quanto é. Mas no geral eu concordo com você.
Maple_shaft
5
Todo desenvolvedor tem pelo menos algumas qualidades ruins, eu sei que não deveria, mas simplesmente não consigo parar :) Toda vez que crio um TODOcomentário, um filhote morre.
Maple_shaft
32
Excluir os comentários de outras pessoas com preconceito está de certa forma forçando seu próprio estilo de programação e crença nos outros. Programadores juniores e pacifistas não latem de volta, mas de vez em quando você se depara com um macho alfa, e então começa uma luta que não deveria ter sido iniciada. Então, você leu em um blog inteligente de uma pessoa inteligente que, quando se trata de comentários, menos é mais. Outros podem não ter lido o mesmo livro. Mesmo que você ache que está certo porque algumas pessoas com SO com 5k + rep concordam, a ditadura não é o caminho para o trabalho colaborativo. Eu trabalhei com um macho alfa antes e desisti.
Job
8
@ Neil Butterworth: re: ructions: O código deve ser maleável. Refatore, mude, melhore. É para isso. Não é para ser escrito apenas uma vez. Nosso entendimento dos negócios muda e, quando isso acontece, precisamos alterar o código. Eu tenho muitos problemas com comentários, mas o mais relevante para a nossa discussão é que os comentários raramente ficam sincronizados com o código, e geralmente eles não explicam por que algo está acontecendo. Quando isso acontece, é fácil excluí-lo. Se alguém vier até mim e perguntar por que eu excluí o seguinte comentário file.Open() // Open the file. Eu ria.
precisa
5
Poucos dias atrás, eu escrevi um pedaço de código, cálculo matemático muito complexo, cheio de trigonometria, transformações, tanto faz ... Levei aproximadamente uma hora e meia para escrever menos de 10 linhas de código. Praticamente ninguém ao meu redor entende como isso funciona. Não vou entender daqui a algumas semanas também. Por outro lado, por que é trivial. Portanto, acima dessas poucas linhas, há um capítulo inteiro do texto, explicando o que, não o porquê. Se você viesse e excluísse esse comentário, eu teria dado um soco na sua cara, parafuso sendo demitido.
Davor Ždralo
76

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.

Neil Butterworth
fonte
14
Eles não apenas mostram outra diferença, mas também podem errar ao longo do tempo, enquanto qualquer bom VCS sempre será capaz de dizer quem realmente escreveu uma linha específica, bem como a história em torno dessa linha. A única coisa pior do que comentários inúteis são comentários prejudiciais. Esses comentários começam como inúteis e eventualmente se tornam prejudiciais, se não totalmente ignorados.
Ben Hocking
10

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.

dietbuddha
fonte
8

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.

John Connelly
fonte
6

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.

Tangurena
fonte
5

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.

Tyanna
fonte
5

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!".

wolfgangsz
fonte
4

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.

DaveE
fonte
1
+1 Eu ia escrever esta resposta, mas você me salvou do problema. Não apenas os procedimentos armazenados são distribuídos como fonte, mas também muitas linguagens de script. Eu uso muito o OpenACS e o TCL - geralmente se um cliente tem uma versão bifurcada de um arquivo específico, a única maneira de ser GARANTIDO é que você saiba qual versão ele possui lendo o log de alterações. Particularmente útil se você estiver conectado ao site de um cliente e não puder fazer diferenças facilmente com o software de controle de versão.
TrojanName
3

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.

whatsisname
fonte
1

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.

Justin Cave
fonte
Existem conversões VCS que não preservam as mensagens de confirmação?
David Thornley
1
@ David - Eu já vi muitas coisas que não. Eu não sei se houve obstáculos técnicos ao fazê-lo, ou se alguém decidiu que era mais fácil apenas "começar de novo" e verificar em todo o código para as novas VCS no dia 1.
Justin Caverna
adicionar um comentário explicando por que um processo alterado pode ser útil e, às vezes, adicionar um comentário explicando quando ele foi alterado, mas não vejo o mérito em colocar esse comentário na forma de um log de alterações. Por um lado, disfarça um pouco a utilidade do comentário ("Oh, é apenas um comentário do log de alterações") e, por outro, incentiva outros comentários desnecessários no log de alterações (reforçando o número 1).
precisa
Parar de usar a fonte visual segura? Todos os sistemas de controle de fonte modernos e úteis lidam adequadamente com os logs de alterações. Sabemos disso por definição porque, se não o fizessem, não seriam considerados úteis. Gaste 30 minutos aprendendo a usar o controle de origem que você possui, o que o tornará muito mais eficaz do que apenas orar a alguém que sabe que suas ferramentas lhe pouparão migalhas. Sem mencionar, muitas vezes o histórico do código é irrelevante, você está apenas testando e escrevendo agora, agora.
Ebyrob 7/11
Quanto à "alteração do controle de origem" - quase todos os sistemas modernos podem mover o histórico um para o outro, gerar arquivos de alteração no nível do projeto individual ou, com um pequeno esforço, incorporar seus registros de alterações no arquivo de origem (quando se tornar apropriado em uma movimentação não antes). Portanto, a tecnologia existe, as pessoas que optam por não usar o controle de origem adequadamente são o problema.
Ebyrob 7/11
1

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?

Sverre Rabbelier
fonte
1
quais licenças dizem isso?
Trasplazio Garzuglio
2
Eu trabalhei em um local onde a conformidade com o Sarbanes Oxley que eles acreditavam exigia blocos de alteração nos arquivos de origem. Eles também usaram o PVCS (também conhecido como "Dimensions") ao longo dos anos, então eles realmente não tinham controle de versão, mas o que eu sabia?
Bruce Ediger
@Marco: não me lembro ou teria vinculado a ele.
Sverre Rabbelier
1
A seção 2a da GPLv2 exige isso. A maioria dos projetos o ignora, alguns têm um único arquivo "ChangeLog" (geralmente gerado a partir de seus VCS).
ADS
0

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.

briddums
fonte
1
Pessoalmente, acho um pouco difícil quando um arquivo de 200 linhas se torna 1.000 linhas devido à adição de um registro de alterações em cada arquivo de origem. Esse ruído extra realmente obscurece o que é importante em pouco tempo.
Ebyrob 7/11