Existe um método para diferenciar comentários informativos do código comentado?

Ao longo da programação, você terminará com alguns comentários que explicam o código e outros que estão removendo o código:

// A concise description 
const a = Boolean(obj);
//b = false;

Existe um bom método para analisar rapidamente qual é qual?

Eu brinquei com o uso de 3 /e /** */para comentários descritivos.

Eu também usei um plugin VSCode para destacar //TODO:e//FIXME:

Existe uma solução muito simples para isso: remova o código comentado.

Realmente, existem apenas duas boas razões para comentar o código: para testar algo / fazer uma correção ou salvar o código que você pode usar mais tarde. Se você estiver testando ou corrigindo algo, remova o código comentado assim que terminar o teste ou a correção. Se você estiver salvando um código que possa usar mais tarde, crie um código de primeira classe e coloque-o em algum lugar, como uma biblioteca, onde ele possa ser usado de maneira adequada.

Adicionando à excelente resposta de @ RobertHarvey, acredito que só tenha encontrado um motivo legítimo para salvar código comentado no controle de origem, mesmo que temporariamente: no caso de código de substituição não óbvio que não deve ou não pode ser usado agora por algum motivo . Mesmo assim, a maior parte do comentário deve ser a explicação, não o código de substituição. Isso pode ser um bug ou um recurso do idioma que ainda não é considerado estável. Pode ser algo como isto:

# TODO: Replace with `foo = frobnicate(bar)` once <link.to/bug> is fixed
foo = [some complex workaround]

Nesse caso, o trabalho já foi concluído, mas você ainda não pode tirar proveito dele, portanto, excluí-lo significa que alguém precisaria redescobri-lo mais tarde. O mesmo vale para soluções abaixo do ideal, que podem parecer superiores à primeira vista ou compensações conscientes contra soluções semelhantes .

Cuidado: não desarrume seu código com soluções alternativas. Cada tarefa pode ser executada de infinitas maneiras diferentes, e não é econômico explorar esse espaço por um longo tempo para cada mudança. As revisões de código podem ser um bom lugar para descobrir esses comentários ausentes, quando o seu colega sugere uma melhoria que você já descobriu que não é ótima.

Hmm, eu li essa pergunta um pouco diferente de Robert, que afirma corretamente que o código comentado deve ser removido.

Se, no entanto, você estiver procurando uma convenção para marcar o código para remoção posterior, um dos meus favoritos antigos é:

//b = false; //TODO: remove

Alguns sinalizadores do IDE //TODO:comentam ou podem ser ensinados. Caso contrário, geralmente é uma string pesquisável. É melhor seguir qualquer convenção estabelecida por sua loja, pois isso pode ser feito de várias maneiras. Toda base de código deve fazer isso de uma maneira. Mantém pesquisável.

analisar rapidamente qual é qual?

Sem essa marca, a maneira automatizada de fazer isso é com o compilador. Se retirar o comentário produz um código compilado, ele deve ter sido um código comentado. Escrever um plugin IDE que verifique se isso não seria difícil. Mas isso deixará o código comentado com erros para trás.

É por isso que é melhor simplesmente marcar o código comentado como código no momento em que você o comentar. Isso permite que você trabalhe de maneira não destrutiva enquanto decide se realmente deseja que ele desapareça. Como todos somos interrompidos e esquecemos um pouco, não se surpreenda se algumas linhas forem registradas nesse estado. Se o fizerem, é bom que sejam pelo menos claramente marcados e pesquisáveis. Macros de teclado me ajudaram com isso no passado. É difícil ser interrompido no meio disso, se você puder fazer isso com um único toque de tecla.

Você pode levar isso até a marca dos seus testes de integração contínua. Ops, estou tentando verificar novamente com os TODO pendentes.

Uso diretivas de pré-processador para remover o código, sem comentar:

//comment
active_code();
#if FALSE
inactive_code();
#endif

Isso facilita a pesquisa, e meu marcador de sintaxe trata isso como um comentário. Eu posso até recolhê-lo em uma única linha:#if FALSE(...)

Você pode expandir essa ideia para ter várias opções:

#if OPTION == 0
code_for_option_0();
#elif OPTION == 1
code_for_option_1();
#else
code_for_all_other_options();
#endif

E verificação de erros em tempo de compilação:

#if FOO >= 5
#error FOO should be less than 5!
#endif

Claro, você não quer exagerar nisso, ou fica difícil dizer o que realmente está sendo compilado e o que não está. Mas você entendeu a idéia e é o mesmo problema do código comentado ... desde que você o use apenas estaticamente. Se suas condições são dinâmicas, é pior.

Para determinar qual é qual em uma base de código existente que não considerou esse problema, não acho que exista uma solução universal. Você precisará encontrar padrões e provavelmente codificar um regex para encontrá-los.

Concordo com a resposta afirmando que o código antigo deve ser removido em vez de ser comentado, sempre que possível, no entanto, observei uma convenção nessas poucas ocasiões em que o código comentado é necessário.

(Minha base é C #, mas isso pode ser aplicado a qualquer linguagem de sintaxe C, por exemplo, java)

// An explanatory comment has a space between the comment marker and the content.

// The following lines are commented out code so do not have the space (except where indented).
//var a = something();
//if(a==2) {
//   doSomethingElse();
//}

Ainda estou interpretando a pergunta de forma diferente, pensando que você deseja encontrar um código comentado.

É provável que o código no estilo C tenha ponto e vírgula, enquanto é improvável que o comentário tenha ponto e vírgula. Portanto, para o código comentado de linha única, você pode usar esta expressão regular:

\s*\/\/[\s\S]*;

Para código comentado com várias linhas, pode ser

\/\*[^\;]*;[^\;]*\*\/

Nota O Visual Studio é um pouco peculiar sobre as quebras de linha em expressões regulares, elas não contam como espaço em branco, você precisa especificar um \ n explícito.

Se você usar um editor com um compilador em execução em segundo plano (como Xcode e Clang), tente compilar o texto do comentário. Por exemplo, "uma descrição concisa" fornece erros, "b = falso;" não. Você pode usar realce de sintaxe diferente.

Um método mais simples seria um plug-in IDE que usa algumas heurísticas, como várias palavras seguidas, que não sejam palavras-chave, apontam para comentários, apontam para o código, etc.

Outras respostas cobriram variações no tema "não comentar código". Mas, às vezes, você ainda o deseja para referência.

Se você realmente precisa do código para ficar por perto, uma solução melhor é cercá-lo com "#if 0 ... #endif", idealmente com um comentário para dizer o porquê. Esta é a estratégia recomendada de vários padrões de codificação, incluindo MISRA.

Simples, pelo menos para mim - e em C / C ++. Os comentários entre / * * / são informativos. O código de teste removido temporariamente é comentado com // inicial.

E há uma boa razão para deixar o código de teste no arquivo, mas comentado, pelo menos no tipo de trabalho que faço. Cedo ou tarde, alguém desejará fazer uma alteração, que precisará desse código. A descomentação de um bloco requer um comando do editor, assim como o re-comentário quando você terminar.