É uma prática recomendada não excluir arquivos redundantes imediatamente do VCS, mas marcá-los como "A serem excluídos" com comentários primeiro?

Eu queria saber se a maneira como lido com os arquivos de origem que precisam ser excluídos do controle de versão pode ser considerada uma má prática.

Quero explicar para você com base nesse exemplo:

Recentemente, fiquei muito zangado porque tive que classificar tediosamente as classes Java em um programa que era basicamente código morto, mas ele não foi documentado em nenhum lugar e também não foi comentado nessas classes Java. É claro que eles precisavam ser excluídos, mas antes que eu exclua essas coisas redundantes, tenho um hábito - alguns podem dizer estranho -:

Eu não excluo esses arquivos redundantes imediatamente via SVN-> Delete (substitua pelo comando delete do seu sistema de controle de versão de sua escolha), mas em vez disso, coloco comentários nesses arquivos (refiro-me à cabeça e ao rodapé) que eles irão ser excluído + meu nome + a data e também - o mais importante - POR QUE SÃO EXCLUÍDOS (no meu caso, porque estavam mortos, código confuso). Em seguida, eu os salvo e os comprometo com o controle de versão. Da próxima vez que eu tiver que confirmar / fazer o check-in de algo no projeto para o controle de versão, pressione SVN-> Delete e eles serão excluídos no Controle de Versão - ainda é claro que podem ser restaurados por meio de revisões, e é por isso que adotei esse hábito.

Por que fazer isso em vez de excluí-los imediatamente?

Minha razão é que eu quero ter marcadores explícitos pelo menos na última revisão em que esses arquivos redundantes existiam, por que eles mereciam ser excluídos. Se eu excluí-los imediatamente, eles serão excluídos, mas não há nenhum documento sobre por que foram excluídos. Eu quero evitar um cenário típico como este:

"Hmm ... por que esses arquivos foram excluídos? Eu trabalhei bem antes." (Pressiona 'reverter' -> o sujeito que reverteu desapareceu para sempre ou não está disponível nas próximas semanas e o próximo responsável deve descobrir tediosamente como eu sobre o que são esses arquivos)

Mas você não percebe por que esses arquivos foram excluídos nas mensagens de confirmação?

Claro que sim, mas às vezes uma mensagem de confirmação não é lida pelos colegas. Não é uma situação típica que, quando você tenta entender o código (no meu caso, morto), verifique primeiro o log de controle de versão com todas as mensagens de confirmação associadas. Em vez de rastrear o log, um colega pode ver imediatamente que esse arquivo é inútil. Isso economiza seu tempo e ela sabe que esse arquivo provavelmente foi restaurado com defeito (ou pelo menos levanta uma questão).

O problema de adicionar um comentário a um arquivo que deve ser excluído, em vez de excluí-lo no controle de origem e colocar a explicação, é o pressuposto de que, se os desenvolvedores não lerem mensagens de confirmação, eles certamente lerão comentários no código-fonte.

Da perspectiva de alguém de fora, essa metodologia parece estar enraizada em uma visão muito conservadora do controle de origem.

"E se eu excluir este arquivo não utilizado e alguém precisar dele?" alguém pode perguntar.

Você está usando o controle de origem. Reverta a alteração ou, melhor ainda, converse com a pessoa que excluiu o arquivo (comunique).

"E se eu excluir o arquivo morto, alguém começa a usá-lo novamente e faz alterações?" alguém pode perguntar.

Novamente, você está usando o controle de origem. Você terá um conflito de mesclagem que uma pessoa deve resolver. A resposta aqui, como na última pergunta, é se comunicar com seus colegas de equipe.

Se você realmente duvida que um arquivo deve ser removido, comunique-se antes de excluí-lo do controle de origem. Talvez tenha parado de ser usado recentemente, mas um recurso futuro pode exigir isso. Você não sabe disso, mas um dos outros desenvolvedores pode.

Se precisar removê-lo, remova-o. Corte a gordura da base de código.

Se você fez um "oopsie" e realmente precisa do arquivo, lembre-se de que está usando o controle de origem para recuperar o arquivo.

Vincent Savard, em um comentário sobre a questão, disse:

... Se seus colegas não leem as mensagens de confirmação e ressuscitam um arquivo que foi excluído por direito e passa na revisão de código, há definitivamente algo errado em sua equipe e é uma ótima oportunidade para ensiná-los melhor.

Este é um bom conselho. As revisões de código devem pegar esse tipo de coisa. Os desenvolvedores precisam consultar as mensagens de confirmação quando uma alteração inesperada é feita em um arquivo ou um arquivo é removido ou renomeado.

Se as mensagens de confirmação não contam a história, os desenvolvedores também precisam estar escrevendo mensagens de confirmação melhores.

Ter medo de excluir código ou excluir arquivos é indicativo de um problema sistêmico mais profundo com o processo:

• Falta de análises precisas de código
• Falta de entendimento sobre como o controle de origem funciona
• Falta de comunicação da equipe
• Mensagens de confirmação ruins por parte dos desenvolvedores

Esses são os problemas a serem resolvidos, para que você não sinta que está jogando pedras em uma casa de vidro ao excluir código ou arquivos.

Sim, é uma má prática.

Você deve colocar a explicação para a exclusão na mensagem de confirmação ao confirmar a exclusão dos arquivos.

Os comentários nos arquivos de origem devem explicar o código como está atualmente . As mensagens de confirmação devem explicar por que as alterações na confirmação foram feitas; portanto, o histórico de confirmação no arquivo explica seu histórico.

Escrever comentários explicando as mudanças diretamente na própria fonte apenas tornará o código muito mais difícil de seguir. Pense nisso: se você comentar no arquivo toda vez que alterar ou excluir o código, em breve os arquivos serão inundados com comentários sobre o histórico de alterações.

Na minha opinião, ambas as suas opções não são práticas recomendadas , e não práticas ruins :

1. A adição de comentários adiciona algum valor se alguém ler esses comentários.
2. A simples exclusão do VCS (com um motivo na descrição da mudança) pode afetar um produto crítico e muitas pessoas não leem a descrição da mudança, especialmente quando estão sob pressão.

Minha prática preferida - principalmente por ter sido mordida várias vezes ao longo dos anos, tendo em mente que você nem sempre sabe onde ou por quem seu código está sendo usado - é:

1. Adicione um comentário afirmando que é um candidato para exclusão e descontinuação #warning ou similar (a maioria das linguagens possui algum tipo de mecanismo, por exemplo, em Java , no pior caso, uma printdeclaração ou similar será suficiente), idealmente com algum tipo de escala de tempo e com detalhes de contato. Isso alertará qualquer pessoa que ainda esteja usando o código. Esses avisos normalmente estão dentro de cada função ou classe, se essas coisas existirem .
2. Depois de algum tempo, atualize o aviso para um escopo de arquivo padrão #warning(algumas pessoas ignoram os avisos de descontinuação e algumas cadeias de ferramentas não exibem esses avisos por padrão).
3. Posteriormente, substitua o escopo do arquivo #warningpor um #errorou equivalente - isso interromperá o código no momento da criação, mas poderá, se for absolutamente necessário, ser removido, mas a pessoa que o remover não poderá ignorá-lo. (Alguns desenvolvedores não leem ou endereçam avisos ou têm tantos que não conseguem separar os importantes).
4. Por fim, marque o (s) arquivo (s), (na ou após a data de vencimento), como excluídos no VCS.
5. Se excluir um pacote / biblioteca / etc inteiro no estágio de aviso, eu adicionaria um README.txt ou README.html ou similar com as informações de quando e por que está planejado se livrar do pacote e deixar apenas esse arquivo, com um altere para dizer quando foi excluído, como o único conteúdo do pacote por algum tempo após a remoção do restante.

Uma vantagem dessa abordagem é que alguns sistemas de controle de versão (CVS, PVCS etc.) não removerão um arquivo existente no checkout, se ele tiver sido excluído no VCS. Também oferece aos desenvolvedores conscientes, aqueles que corrigem todos os seus avisos, muito tempo para resolver o problema ou apelar para a exclusão. Também força os desenvolvedores restantes a olhar pelo menos o aviso de exclusão e reclamar muito .

Observe que #warning/ #erroré um mecanismo C / C ++ que causa um aviso / erro seguido pelo texto fornecido quando o compilador encontra esse código, java / java-doc possui @Deprecatedanotação para emitir um aviso de uso e @deprecatedfornecer algumas informações, etc. receitas para fazer similar em python e eu já vi assertusadas para fornecer informações semelhantes às #errordo mundo real.

Sim, eu diria que é uma má prática, mas não porque está nos arquivos versus na mensagem de confirmação. O problema é que você está tentando fazer uma alteração sem se comunicar com sua equipe.

Sempre que você fizer alguma alteração no tronco - adicionando, excluindo ou modificando arquivos de qualquer maneira - você deve, antes de se comprometer com o tronco, conversar sobre essas alterações diretamente com um membro (ou membros) da equipe que seria diretamente conhecedor deles (essencialmente, discuta o que você colocaria nesses cabeçalhos diretamente com seus colegas de equipe). Isso garantirá que (1) o código que você está excluindo realmente precise ser excluído e (2) sua equipe tenha muito mais chances de saber que o código foi excluído e, portanto, não tente reverter suas exclusões. Sem mencionar que você também terá detecção de bugs e similares para o código que você adicionar.

Obviamente, quando você muda coisas importantes, também deve colocá-las na mensagem de confirmação, mas como já discutiu, não precisa ser a fonte de anúncios importantes. A resposta de Steve Barnes também aborda algumas boas estratégias a serem usadas se o grupo potencial de usuários para o seu código for muito grande (por exemplo, usando os marcadores obsoletos do seu idioma em vez de excluir os arquivos primeiro).

Se você não deseja demorar tanto sem confirmar (ou seja, sua alteração faz mais sentido em várias revisões), é uma boa idéia criar uma ramificação a partir do tronco e confirmar com a ramificação, depois mesclar a ramificação novamente no tronco quando o mudança está pronta. Dessa forma, o VCS ainda está fazendo backup do arquivo para você, mas suas alterações não estão afetando o tronco de forma alguma.

Um problema relacionado a projetos criados em várias plataformas e configurações. Só porque eu determino que ele está morto não significa que é uma determinação correta. Observe que o uso inativo ainda pode significar dependência vestigial que ainda precisa ser eliminada, e alguns podem ter sido perdidos.

Então (em um projeto C ++) eu adicionei

#error this is not as dead as I thought it was

E fez o check-in. Aguarde o processo de reconstrução de todas as plataformas normais e ninguém reclame. Se alguém o encontrasse, seria fácil remover uma linha, em vez de ficar perplexo com um arquivo ausente.

Concordo em princípio que os comentários mencionados estão duplicando o recurso que deve ser feito no sistema de gerenciamento de versões . Mas, você pode ter razões específicas para complementar isso. Não conhecer a ferramenta VCS não é um deles.

No continuum de más práticas, isso é bem menor. Farei isso de vez em quando, quando quiser verificar uma ramificação e poder ver o código antigo. Isso pode facilitar a comparação com o código de substituição. Normalmente, recebo um comentário de revisão de código "cruft". Com uma pequena explicação, passo na revisão de código.

Mas esse código não deve durar muito. Geralmente, eu apago no início do próximo sprint.

Se você tem colegas de trabalho que não leem mensagens de confirmação ou não perguntam por que você deixou o código no projeto, seu problema não é de estilo ruim de codificação. Você tem um problema diferente.

você também pode refatorar a classe e renomeá-la com um prefixo para UNUSED_Classname antes de executar seu truque. Então você também deve confirmar diretamente a operação de exclusão

• Etapa 1: renomear classe, adicionar seu comentário, confirmar
• Etapa 2: excluir arquivo e confirmar

Se for um código morto, exclua-o. Qualquer um que precisar, pode voltar, mas a etapa de renomeação os impedirá de usá-lo diretamente, sem pensar.

Também ensine às pessoas como examinar todas as mensagens de confirmação de um arquivo, algumas pessoas nem sabem que isso é possível.