A maioria das respostas se concentra em como refatorar esse caso específico, mas deixe-me oferecer uma resposta geral sobre o motivo pelo qual o código comentado geralmente é ruim:
Primeiro, o código comentado não é compilado. Isso é óbvio, mas significa que:
-
O código pode nem funcionar.
-
Quando as dependências do comentário mudam, obviamente não irá quebrar.
O código comentado é muito "código morto". Quanto mais tempo ele fica lá, mais ele apodrece e fornece menos e menos valor para o próximo desenvolvedor.
Em segundo lugar, o objetivo não é claro. Você realmente precisa de um comentário mais longo que forneça contexto para o motivo de haver linhas comentadas aleatoriamente. Quando vejo apenas uma linha de código comentada, tenho que pesquisar como ela chegou lá apenas para entender por que ela chegou lá. Quem escreveu isso? O que cometer? Qual foi a mensagem / contexto de commit? Etcetera.
Considere alternativas:
- Se o objetivo for fornecer exemplos de uso de uma função / api, forneça um teste de unidade. Os testes unitários são códigos reais e serão interrompidos quando não estiverem mais corretos.
- Se o objetivo é preservar uma versão anterior do código, use o controle de origem. Eu prefiro dar uma olhada em uma versão anterior e alternar os comentários em toda a base de código para "reverter" uma alteração.
- Se o objetivo for manter uma versão alternativa do mesmo código, use o controle de origem (novamente). É para isso que os ramos são, afinal.
- Se o objetivo é esclarecer a estrutura, considere como você pode reestruturar o código para torná-lo mais óbvio. A maioria das outras respostas são bons exemplos de como você pode fazer isso.