Por que é errado comentar o código e removê-lo gradualmente para acompanhar o que já fiz e o que resta fazer?

Sempre que descubro que grande parte do meu código precisa ser alterada, seja porque está incorreta ou porque precisa ser adaptada às principais mudanças arquiteturais necessárias por outros motivos, é o que normalmente faço:

1. Comento todo o código que suspeito que possa ter que ser alterado. Trato o código comentado como uma espécie da minha lista de tarefas.
2. Eu gradualmente reviso o código comentado e descomente as partes deste código, copio e colo-as em outro local e as edito conforme necessário, ou reescrevo partes desse código do zero, observando o código comentado para referência. Sempre que penso que termino com uma parte do código comentado, eu o removo.
3. Continuo assim até que não consiga ver mais nenhum código comentado.

Devo observar que estou fazendo isso amplamente no projeto pessoal que estou desenvolvendo sozinho.

No entanto, me disseram que eu deveria parar de fazer isso. Foi-me dito que, em vez disso, eu deveria começar a usar o git, referindo-se aos antigos commit para ver o código antigo, em vez de deixar o código comentado. Me disseram:

Comentar código é um mau hábito que deve ser eliminado. Você não tem experiência e não entende isso. Se, em alguns anos, você vir o código de outra pessoa que gosta de comentar o código, começará a xingar essa pessoa. Sempre que vejo um código comentado, removo-o por completo, sem sequer olhar para ele, porque geralmente esse código é completamente inútil. Você certamente deixará de ver as desvantagens de comentar o código em pequenos projetos de uma pessoa; mas se você encontrar um emprego e manter esse hábito, será uma pena.

Posso perguntar quais são essas desvantagens do que estou fazendo que não estou conseguindo ver agora?

Devo dizer que não estou realmente interessado apenas em usar o git para ver o código do passado. Como eu disse, trato comentar o código como uma espécie de lista de tarefas; embora o git me mostre como o código costumava estar, ele falhará em me mostrar claramente quais partes do código ainda precisam ser revisadas e quais já foram concluídas. Temo que possa perder alguma parte do código e introduzir bugs.

Para completar, acho que devo acrescentar que a pessoa que estou citando é uma desenvolvedora experiente e fã do "Código Limpo" do tio Bob - e o tio Bob criticou o comentário severo do código em seu livro.

Se você finalmente remover todo o código comentado, não vejo nenhum problema real com isso. Deixar o código comentado em sua base de código é uma prática ruim, mas não é isso que você está fazendo se trabalhar com tudo e eliminá-lo. Eu suspeito que a pessoa com quem você está conversando não entende o processo que está usando ou está sendo dogmática.

Na realidade, o código comentado é inofensivo. O problema é que é confuso e dificulta a leitura. Existem pecados muito piores, mas é uma coisa muito simples de eliminar. Como a pessoa que comentou o código, você está na melhor posição para determinar que ele pode ser completamente removido.

Muitos IDEs e editores de código entendem algum tipo de sintaxe 'TODO' nos comentários. Essa é uma maneira alternativa de marcar o que precisa ser alterado. Você pode considerar isso, pois fornece um pouco mais de informações sobre o que você estava pensando quando o marcou.

No final do dia, faça as coisas da maneira que resultar no melhor resultado para você. Mesmo que este fosse um projeto de equipe, desde que você remova todo o código comentado, não estará sobrecarregando mais ninguém.

Posso perguntar quais são essas desvantagens do que estou fazendo que não estou conseguindo ver agora?

Indiscutivelmente, nenhum se você trabalha sozinho e não usa o controle de versão e sente que está bem em fazê-lo dessa maneira.

De fato, sem controle de versão, não importa muito o que você faz em qualquer momento do "tempo", pois o código é sempre o estado em que o arquivo atual é "salvo", como no sistema operacional.

Se você usa o controle de versão e tem muitos comentários como sua "lista de tarefas", corrige alguns e remove o comentário, repete, repita etc ... você tem o código "trabalho em andamento" e os comentários são salvos no seu histórico de revisões. Isso não será um problema se você nunca precisar reverter para outro commit ou até mesmo "escolher cereja" mais tarde (este é o local onde você aceita commits específicos e os puxa para outro ramo a ser usado). Mas, caso contrário, pode ser um problema.

Indiscutivelmente, isso pode ser comparado aos "snap shots" do software do disco rígido, como o Windows (a coisa de Restauração). Se você tirar um instantâneo com um vírus, você o matará, mas depois precisará retroceder, e poderá voltar a um ponto em que o vírus está presente novamente.

É provável que essa abordagem também seja um problema quando você usa o controle de versão e trabalha com outros desenvolvedores, pois eles precisam ver sua lista de tarefas que não tem utilidade para eles. Na verdade, é apenas a desordem que eles precisam ignorar e contornar. Em nossas equipes, sempre removemos todos os comentários, como código antigo ou "notas". A menos que sejam úteis - no entanto, isso é muito raro, porque temos documentação para "como funciona" e software para rastrear o que precisa ser feito (também conhecido como todo).

Além disso, ao trabalhar em um projeto maior, você tende a colaborar, a se comprometer e a enviar com frequência, para que seja possível que o ramo em que estão trabalhando tenha sua lista TODO se eles mesclarem seu ramo ao deles. Então sua lista TODO é da conta de todos: D

Em resumo, se você não trabalha sozinho e, especialmente, ao usar o controle de versão, ele desorganiza o histórico e pode ser desorganizado para outros desenvolvedores.

E isso é algo pessoal em alguns aspectos, mas usar uma base de código como sua "lista de tarefas" não é realmente ideal. Um dia, você pode deixar algo por acidente ou esquecer de comentar ou descomentar por engano.

Como em muitas abordagens de arquitetura, codificação e como você ou sua equipe trabalham, cada cenário pode exigir algo diferente. Portanto, considere as desvantagens mencionadas e os benefícios do uso do controle de versão e decida se funciona para você .

Parece que seu revisor é um pouco dogmático. Não tenho certeza de que xingar alguém por comentar código é PC ;-), ou até útil ;-)

Mas, mais seriamente, acho que seu revisor está certo, que você deveria considerar seriamente o uso do git (ou de algum outro sistema de controle de fonte, mas o git é uma escolha sensata).

E isso pode aliviar algumas das suas necessidades para comentar o código.

Mas ter uma lista TODO dentro do código (listas com marcadores ou código antigo) - é bastante razoável na minha opinião. Mas você pode reconsiderar um pouco sobre como fazê-lo. Por um lado, sugiro pensar em outra pessoa lendo seu código. Que outra pessoa poderia ser você, um ano depois que você desistiu e ingressou em um projeto. Ou poderia ser outra pessoa completamente. APENAS encontrar o código comentado é um pouco confuso. Talvez algo como:

/*
 * Need this sort of functionality added back before too long:
 * .... OLD CODE HERE
 */

Pessoalmente, eu me inclino mais para algo assim:

 * TODO:
 *      @todo   Possible get rid of intermediate LRUCache_ object.
 *
 *      @todo   Find some reasonable/simple way to get
 *              LRUCache<PHRShortcutSpec, PHRShortcutSpec, PHRShortcutSpecNoAuthCacheTraits_>   sRecentlyUsedCache (kMaxEltsInReceltlyUsedCache_);
 *              Working with ONE T argument
 *              Add(elt2cache).
 ...

e sinto-me à vontade para inserir 'trechos de código' do código antigo como úteis.

Usar o git é difícil (infelizmente). Você levará um tempo para aprender e pode parecer que não faz parte do que você está tentando realizar. Mas se você pretende programar de maneira útil, precisará aprender a fazer isso como parte de uma equipe, e se comunicar com uma equipe, e o git é exatamente isso que é feito hoje em dia. E depois que você começar a usá-lo, encontrará uma ferramenta / muleta MUITO útil, facilitando o desenvolvimento de seu software.

Boa sorte!

Existem muitas razões para comentar o código: -

• Ainda não está certo, e você não comentará quando estiver pronto.
• Você está comentando temporariamente sobre a alteração do comportamento durante a depuração.
• Você não tem certeza se o código é necessário, mas não deseja excluí-lo até testar um pouco mais.
• O código é necessário para algumas versões do software, mas não esta.
• O código é obsoleto, mas levou séculos para ser escrito e você está emocionalmente ligado a ele. Além disso, pode ser útil um dia.

O problema surge quando você coloca o código na cama e volta a ele alguns anos depois para fazer alguma manutenção. Você encontrará a base de código repleta de códigos comentados. Não ficará mais claro por que algo está lá, e agora é apenas desorganização.

Se você usar qualquer ferramenta de controle de versão meio decente, poderá excluir com ousadia qualquer código que não precise mais, seguro com o conhecimento de que o sistema de controle de versão ainda o armazena. Um arquivo diff entre versões revelará o que foi excluído. Depois de implementar o controle de versão, a única necessidade de comentar é para coisas temporárias. Se você encontrar um código comentado em arquivos nos quais não está trabalhando, basta excluí-lo.

Não vou reiterar por que você deve usar o controle de origem mesmo em projetos de uma pessoa, pois existem muitos outros recursos por aí que o instruem a fazer isso. Mas uma das principais desvantagens relacionadas à sua abordagem atual é que, se você comentar o código, o oculta do IDE (se não estiver usando um IDE, provavelmente o deverá considerar).

Por exemplo, se você deseja renomear um método ou classe ou alterar o número de parâmetros que um método utiliza, seu IDE deve ter uma opção de refatoração para fazer isso, que encontrará todas as referências apropriadas e as atualizará adequadamente - mas provavelmente vencerá ' t procure nos comentários.

Em vez de tentar adivinhar onde você precisa fazer alterações, apenas faça-as e deixe seu IDE informar onde suas alterações causaram falhas. Em seguida, você pode comentar o código mais cirurgicamente e, esperançosamente, por um curto período de tempo antes de corrigir o que quebrou.

É ruim e você deve parar .

O motivo se resume a tentar fazer uma grande quantidade de refatoração de uma só vez.

Se você comentar grandes seções de código, corrija um pouco e faça o check-in, então você fez o check-in do código não-funcional. e um monte de coisas comentadas que outras pessoas assumirão que são antigas e podem ser ignoradas

Se você não fizer check-in com frequência, estará acumulando conflitos de mesclagem e não registrando o progresso passo a passo.

Você precisa mudar sua prática de trabalho para que, se precisar parar no meio do caminho, tudo ainda funcione.

Dê pequenos passos e faça o check-in após cada um:

• extrair uma interface
• escreva um teste
• refatorar uma função

Não marque grandes pedaços de código como 'seus' comentando-os e leve-os para trabalhar sozinho até que estejam completos ou você falhar.

Se você precisar acompanhar o que precisa ser feito, use um quadro de tarefas como scrum ou trello