O código comentado pode ser uma documentação valiosa?

Eu escrevi o seguinte código:

if (boutique == null) {
    boutique = new Boutique();

    boutique.setSite(site);
    boutique.setUrlLogo(CmsProperties.URL_FLUX_BOUTIQUE+fluxBoutique.getLogo());
    boutique.setUrlBoutique(CmsProperties.URL_FLUX_BOUTIQUE+fluxBoutique.getUrl());
    boutique.setNom(fluxBoutique.getNom());
    boutique.setSelected(false);
    boutique.setIdWebSC(fluxBoutique.getId());
    boutique.setDateModification(new Date());

    boutiqueDao.persist(boutique);
} else {
    boutique.setSite(site);
    boutique.setUrlLogo(CmsProperties.URL_FLUX_BOUTIQUE+fluxBoutique.getLogo());
    boutique.setUrlBoutique(CmsProperties.URL_FLUX_BOUTIQUE+fluxBoutique.getUrl());
    boutique.setNom(fluxBoutique.getNom());
    //boutique.setSelected(false);
    boutique.setIdWebSC(fluxBoutique.getId());
    boutique.setDateModification(new Date());

    boutiqueDao.merge(boutique);
}

Há uma linha comentada aqui. Mas acho que isso torna o código mais claro, tornando óbvia a diferença entre ife else. A diferença é ainda mais visível com o realce de cores.

Comentar códigos como esse pode ser uma boa idéia?

A maioria das respostas se concentra em como refatorar esse caso específico, mas deixe-me oferecer uma resposta geral para o motivo pelo qual o código comentado geralmente é ruim:

Primeiro, o código comentado não é compilado. Isso é óbvio, mas significa que:

1. O código pode nem funcionar.

2. Quando as dependências do comentário mudam, obviamente não será interrompido.

O código comentado é muito "código morto". Quanto mais ele fica lá, mais apodrece e fornece cada vez menos valor ao próximo desenvolvedor.

Segundo, o objetivo não é claro. Você realmente precisa de um comentário mais longo que forneça contexto para o motivo de existirem linhas comentadas aleatoriamente. Quando vejo apenas uma linha de código comentada, tenho que pesquisar como chegou lá apenas para entender por que chegou lá. Quem escreveu isso? O que comprometer? Qual foi a mensagem / contexto de confirmação? Etcetera.

Considere alternativas:

• Se o objetivo for fornecer exemplos de uso de uma função / API, faça um teste de unidade. Os testes de unidade são um código real 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. Prefiro fazer check-out de uma versão anterior do que alternar os comentários em toda a base de código para "reverter" uma alteração.
• Se o objetivo é manter uma versão alternativa do mesmo código, use o controle de origem (novamente). Afinal, é para isso que servem os ramos.
• 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.

O maior problema com esse código é que você duplicou essas 6 linhas. Depois de eliminar essa duplicação, esse comentário é inútil.

Se você criar um boutiqueDao.mergeOrPersistmétodo, poderá reescrever isso como:

if (boutique == null) {
    boutique = new Boutique();
    boutique.setSelected(false);
}

boutique.setSite(site);
boutique.setUrlLogo(CmsProperties.URL_FLUX_BOUTIQUE+fluxBoutique.getLogo());
boutique.setUrlBoutique(CmsProperties.URL_FLUX_BOUTIQUE+fluxBoutique.getUrl());
boutique.setNom(fluxBoutique.getNom());
boutique.setIdWebSC(fluxBoutique.getId());
boutique.setDateModification(new Date());

boutiqueDao.mergeOrPersist(boutique);

O código que cria ou atualiza um determinado objeto é comum; portanto, você deve resolvê-lo uma vez, por exemplo, criando um mergeOrPersistmétodo. Você certamente não deve duplicar todo o código de atribuição para esses dois casos.

Muitos ORMs criaram suporte para isso de alguma forma. Por exemplo, eles podem criar uma nova linha se idfor zero e atualizar uma linha existente se idnão for zero. A forma exata depende do ORM em questão e, como não estou familiarizado com a tecnologia que você está usando, não posso ajudá-lo.

Se você não deseja criar um mergeOrPersistmétodo, deve eliminar a duplicação de alguma outra maneira, por exemplo, introduzindo um isNewBoutiquesinalizador. Isso pode não ser bonito, mas ainda é muito melhor do que duplicar toda a lógica de atribuição.

bool isNewBoutique = boutique == null;
if (isNewBoutique) {
    boutique = new Boutique();
    boutique.setSelected(false);
}

boutique.setSite(site);
boutique.setUrlLogo(CmsProperties.URL_FLUX_BOUTIQUE + fluxBoutique.getLogo());
boutique.setUrlBoutique(CmsProperties.URL_FLUX_BOUTIQUE + fluxBoutique.getUrl());
boutique.setNom(fluxBoutique.getNom());
boutique.setIdWebSC(fluxBoutique.getId());
boutique.setDateModification(new Date());

if (isNewBoutique)
    boutiqueDao.persist(boutique);
else
    boutiqueDao.merge(boutique);

Esta é uma ideia absolutamente horripilante . Não fica claro qual é a intenção. O desenvolvedor comentou a linha por engano? Para testar alguma coisa? O que está acontecendo?!

Além do fato de que vejo 6 linhas absolutamente iguais nos dois casos. Em vez disso, você deve impedir essa duplicação de código. Então ficará mais claro que, em um caso, você também chama setSelected.

Não, é uma péssima ideia. Com base nesse código, os seguintes pensamentos vêm à minha mente:

• Esta linha é comentada porque o desenvolvedor a estava depurando e esqueceu de restaurar a linha para seu estado anterior
• Esta linha é comentada porque já fez parte da lógica de negócios, mas não é mais o caso
• Esta linha é comentada porque causou problemas de desempenho na produção e o desenvolvedor queria ver qual era o impacto em um sistema de produção

Depois de ver milhares de linhas de código comentado, agora estou fazendo a única coisa sensata quando o vejo: removo-o imediatamente.

Não há razão sensata para fazer check-in do código comentado em um repositório.

Além disso, seu código usa muita duplicação. Sugiro que você otimize isso para facilitar a leitura humana o mais rápido possível.

Gostaria apenas de acrescentar à resposta de CodesInChaos, apontando que você pode refatorá-la ainda mais em métodos pequenos . Compartilhar funcionalidades comuns por composição evita os condicionais:

function fill(boutique) {    
  boutique.setSite(site);
  boutique.setUrlLogo(CmsProperties.URL_FLUX_BOUTIQUE+fluxBoutique.getLogo());
  boutique.setUrlBoutique(CmsProperties.URL_FLUX_BOUTIQUE+fluxBoutique.getUrl());
  boutique.setNom(fluxBoutique.getNom());
  boutique.setIdWebSC(fluxBoutique.getId());
  boutique.setDateModification(new Date());
}    

function create() {
  boutique = new Boutique();      
  fill(boutique);
  boutique.setSelected(false);
  return boutiqueDao.persist(boutique);
}

function update(boutique) {
  fill(boutiquie);
  return boutiquieDao.merge(boutique); 
}

function createOrUpdate(boutique) {
  if (boutique == null) {
    return create();
  }
  return update(boutique);  
}

Embora esse claramente não seja um bom argumento para o código comentado, há uma situação que eu acho que merece:

// The following code is obvious but does not work because of <x>
// <offending code>
<uglier answer that actually does work>

É um aviso para quem vê mais tarde que a melhoria óbvia não é.

Edit: Estou falando de algo pequeno. Se for grande, você explica.

Neste exemplo específico, considero o código comentado muito ambíguo, principalmente pelas razões descritas na resposta de Dibkke . Outros sugeriram maneiras de refatorar o código para evitar até a tentação de fazer isso. No entanto, se isso não for possível por algum motivo (por exemplo, as linhas são semelhantes, mas não suficientemente próximas), eu gostaria de um comentário como:

// Não é necessário desmarcar esta boutique, porque [WHATEVER]

No entanto, acho que há algumas situações em que deixar (ou mesmo adicionar comentários) código não é repreensível. Ao usar algo como MATLAB ou NumPY, geralmente é possível escrever um código equivalente que 1) itera sobre uma matriz, processando um elemento de cada vez ou 2) opera a matriz inteira de uma só vez. Em alguns casos, o último é muito mais rápido, mas também muito mais difícil de ler. Se eu substituir algum código por seu equivalente vetorizado, incorporei o código original em um comentário próximo, como este:

%% O código vetorizado abaixo faz isso:

% for ii in 1:N
%    for jj in 1:N
%      etc.

%, mas a versão da matriz é executada ~ 15x mais rapidamente na entrada típica (MK, 10/03/2013)

Obviamente, é preciso cuidar para que as duas versões realmente façam a mesma coisa e que o comentário permaneça sincronizado com o código real ou seja removido se o código for alterado. Obviamente, as advertências usuais sobre otimização prematura também se aplicam ...

A única vez que vi o código comentado útil foi nos arquivos de configuração, onde o código para todas as opções é fornecido, mas comentado, facilitando a ativação das configurações, removendo apenas os marcadores de comentário:

## Enable support for mouse input:
# enable_mouse = true

Nesse caso, o código comentado ajuda a documentar todas as opções disponíveis e como usá-las. Também é convencional usar os valores padrão por toda parte, portanto o código também está documentando as configurações padrão.

De um modo geral, o código é apenas auto-documentado para a pessoa que escreveu o código. Se a documentação for necessária, escreva a documentação. É inaceitável esperar que um desenvolvedor novo em uma base de código-fonte se sente sentado lendo milhares de linhas de código para tentar descobrir de alto nível o que está acontecendo.

Nesse caso, o objetivo da linha de código comentada é mostrar a diferença entre duas instâncias do código duplicado. Em vez de tentar documentar a diferença com um comentário, reescreva o código para que faça sentido. Então, se você ainda achar necessário comentar o código, escreva um comentário apropriado.

Não, o código comentado fica obsoleto e logo é pior do que inútil, geralmente é prejudicial, pois cimenta algum aspecto da implementação, juntamente com todas as suposições atuais.

Os comentários devem incluir detalhes da interface e função pretendida; "função pretendida": pode incluir, primeiro tentamos isso, depois tentamos isso, depois falhamos dessa maneira.

Os programadores que eu vi tentando deixar as coisas nos comentários estão apaixonados pelo que escreveram, não querem perdê-lo, mesmo que não esteja adicionando nada ao produto final.

Pode ser em casos muito raros, mas não como você fez. As outras respostas explicaram muito bem as razões para isso.

Um dos raros casos é uma especificação de modelo RPM que usamos em minha loja como ponto de partida para todos os novos pacotes, principalmente para garantir que nada de importante seja deixado de fora. A maioria, mas nem todos os nossos pacotes têm um pacote contendo fontes com um nome padrão e especificado com uma tag:

Name:           foomatic
Version:        3.14
 ...
Source0:        %{name}-%{version}.tar.gz

Para pacotes sem fontes, comentamos a tag e colocamos outro comentário acima dela para manter o formato padrão e indicar que alguém parou e pensou no problema como parte do processo de desenvolvimento:

Name:           barmatic
Version:        2.71
 ...
# This package has no sources.
# Source0:        %{name}-%{version}.tar.gz

Você não adiciona o código que sabe que não será usado porque, como outros já explicaram, pode ser confundido com algo que pertence a ele. Pode. no entanto, seja útil adicionar um comentário explicando por que falta o código esperado:

if ( condition ) {
  foo();
  // Under most other circumstances, we would do a bar() here, but
  // we can't because the quux isn't activated yet.  We might call
  // bletch() later to rectify the situation.
  baz();
}

O código comentado não é usado pelo aplicativo, portanto, ele precisa ser acompanhado por outros comentários, informando por que ele não está sendo usado. Mas dentro desse contexto, são situações em que código comentado-out podem ser úteis.

O que me vem à cabeça é um caso em que você resolve um problema usando uma abordagem comum e atraente, mas depois acontece que os requisitos do seu problema real são ligeiramente diferentes desse problema. Especialmente se seus requisitos exigirem consideravelmente mais código, a tentação dos mantenedores de "otimizar" o código usando a abordagem antiga provavelmente será forte, mas isso só trará o bug de volta. Manter a implementação "errada" nos comentários ajudará a dissipar isso, porque você pode usá-la para ilustrar exatamente por que essa abordagem está errada nessa situação.

Não posso imaginar que isso ocorra com muita frequência. Normalmente, deve ser suficiente explicar as coisas sem incluir uma implementação "errada" de amostra. Mas posso imaginar um caso em que isso não seja suficiente; portanto, como a pergunta é se ela pode ser útil, sim, pode. Apenas não na maioria das vezes.

Isso não parece bom amigo.

O código comentado é ... apenas não o código. O código é para implementação da lógica. Tornar um código mais legível por si só é uma arte. Como o @CodesInChaos já sugeriu que linhas de código repetitivas não são uma implementação muito boa da lógica .

Você realmente acha que um verdadeiro programador prefere a legibilidade à implementação lógica. (pela maneira como temos comentários e 'complementos' para colocar em nossa representação lógica).

No que me diz respeito, deve-se escrever um código para o compilador e isso é bom - se 'ele' entender esse código. Para legibilidade humana, os comentários são bons, para os desenvolvedores (a longo prazo), para as pessoas que reutilizam esse código (por exemplo, testadores).

Caso contrário, você pode tentar algo mais flexível aqui, algo como

boutique.setSite (site) pode ser substituído por

setsiteof.boutique (site). Existem diferentes aspectos e perspectivas do POO através dos quais você pode aumentar a legibilidade.

Embora esse código pareça muito atraente a princípio, pode-se pensar que ele encontrou um caminho para a legibilidade humana, enquanto o compilador também faz seu trabalho perfeitamente, e todos nós começamos a seguir essa prática, o que levará a um arquivo difuso que ficará menos legível no tempo e mais complexo, pois ele se expandirá.