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

38

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:

Ás
fonte
2
Como uma nota, ///e /** ... */comentários também são utilizados por alguns geradores de documentação, tais como Doxygen ou JSDoc. Se você os usar ou ferramentas semelhantes, talvez não seja possível usar esse tipo de comentário para comentários descritivos que não pretendem fazer parte da documentação.
Justin Time 2 Restabelecer Monica
11
Em javascript, a maioria das linhas de código provavelmente terminará com ponto e vírgula. A menos que seus comentários o façam, isso parece bastante simples, e você também pode escrever um script para verificar isso com facilidade;
Artemis Fowl

Respostas:

189

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.

Robert Harvey
fonte
108
Além disso, se o código foi verificado: basta removê-lo. Se você precisar de volta, o controle de fonte o
protege
38
Quando o código é removido, ninguém percebe que ele já existiu. Isso dificulta a recuperação. Há valor em deixar o código comentado, especialmente se parece provável que ele será usado no futuro.
usr
76
@usr: Quando o código é removido, ninguém percebe que ele já existiu - e, para minha experiência, em 99% de todos os casos do mundo real é a coisa certa. Em 1%, pode haver algum valor nas linhas comentadas; no entanto, se o código comentado permanecer por várias semanas ou meses (ou mais), as chances são altas de que ele não será mais compilado devido às refatorações do ativo linhas de código. O argumento "valor pontencial para usos futuros" é frequentemente usado como desculpa errada por pessoas que têm um problema emocional de retirar coisas da base de código pelas quais investiram algumas horas de trabalho cerebral.
Doc Brown
21
Eu nunca cometo código comentado sem comentários explicativos adicionais. Existem situações raras em que você pode querer o código de volta no curto prazo, mas cada uma delas é excepcional e requer uma explicação para futuros desenvolvedores (ou futuros você). 90% dos meus comentários são "Removidos porque parecem não ter sido utilizados. Exclua após novembro de 2021 se não houver problemas"
James Beninger 06/07
31
Meu colega disse uma vez "Havia um código aqui que executava o X, mas eu o removi" quando removemos algum recurso por enquanto. Isso funcionou muito bem; você sabia que estava no histórico de origem desse arquivo, mas não estava incomodando.
Erik
45

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.

l0b0
fonte
2
O outro lado disso é que às vezes você precisa explicar por que não está usando frobnicate(bar), para que ninguém apareça e tente "consertar" seu código "deselegante". Então, você mostra a eles que sabe que, em um mundo perfeito, a frobnicatefunção seria o caminho a percorrer, mas, por experiência dolorosa, ela não funciona corretamente. Pode não haver expectativa de que o terceiro considere um bug, muito menos vale a pena consertar; você ainda precisa deixar um comentário para futuros programadores (inclusive você) sobre por que você não adotou a abordagem óbvia.
Monty Harder
3
Uma situação relacionada é que pode haver duas maneiras de fazer algo, uma das quais processará dados válidos muito mais rapidamente que a outra, e uma delas oferecerá diagnósticos mais úteis se, por qualquer motivo, receber dados inválidos. Se o programa fizer parte de um processo que só deve alimentar dados "garantidos" como válidos, mas algo no processo não está funcionando corretamente, ter disponível uma versão mais lenta, mas com melhores diagnósticos, pode torná-lo muito mais fácil determinar o que está errado.
supercat 8/07
20

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.

candied_orange
fonte
Em vez de ver se os comentários são compilados para rotulá-los como código, você pode executar os comentários por meio de um processador de linguagem natural e rotular os que analisam como uma frase ou frase substantiva no idioma que sua equipe fala.
TheHansinator 6/07
3
@TheHansinator parece bom, mas minha experiência com o relacionamento correto com meus celulares com o jargão do meu codificador me deixa cauteloso.
candied_orange
Eu imagino que a PNL usada para analisar comentários de código seria muito melhor do que a PNL que habilita a correção automática, simplesmente porque o computador tem a frase inteira para trabalhar e não está tentando corrigir erros de ortografia. Sem mencionar que o falso negativo também é melhor aqui - desde que um humano seja capaz de revisar o comentário antes da exclusão, ele pode apenas reescrevê-lo, em vez de não ser alertado sobre o uso inútil do gobbledygook.
TheHansinator 07/07
3
wrt parsing: double buffer (flip on)-> protótipo C ou inglês ultra-conciso? não pode dizer sem contexto, não é uma construção inteira correta em qualquer idioma. Alguns falsos positivos e negativos são inevitáveis, quando os comentários por natureza não restringem a forma de seu conteúdo em nenhuma direção.
Leushenko 07/07
8

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.

AaronD
fonte
Para que isso seria bom? Você precisa compilar várias versões?
Tvde1 8/07
@ Tvde1 Essa é uma possibilidade e um pesadelo em potencial, se você não a administrar muito bem. Mas a alternativa é possivelmente pior. Se você tiver várias cópias quase do mesmo código, uma para cada variação em um tema comum, precisará mantê-las separadamente e em sincronia.
AaronD 8/07
Existem várias maneiras de fazer isso, mas todas elas apresentam alguma variação do complexo problema de configuração ou do problema da cópia independente: Você tem certeza de que um bugfix chegou a todas as cópias independentes? E se não, e outro recurso for adicionado, ele será quebrado pela correção de bug que era conhecida antes do recurso, mas que não foi portada até agora?
AaronD 8/07
3
Isso só funciona se você tiver uma etapa de pré-processamento como C. A questão é sobre javascript. Você poderia fazer um pré-processamento, mas isso aumentará os recursos do sistema de compilação e também não é padrão. Se você não possui um sistema de compilação ou o sistema de compilação não oferece suporte à análise e execução de código, não será possível implementar esta solução. Finalmente, nem sequer aborda a questão - o código comentado não é estritamente equivalente ao código que é ativado condicionalmente. Pode ser uma sobra que não deve ser ativada.
VLAZ
A ativação condicional é apenas uma extensão da resposta e não a resposta em si. Caso contrário, eu o editaria para incluir os comentários que o estendem ainda mais.
AaronD 8/07
4

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();
//}
IanF1
fonte
2
Isso depende totalmente do estilo: quando eu comento o código, geralmente adiciono a //primeira coluna e, como praticamente todo o código é recuado, o resultado é quase sempre sempre que o comentário começa com algumas guias. Comentários normais não recebem um espaço à esquerda de mim, a menos que já existam outros comentários com um espaço à esquerda nas proximidades. Portanto, seu método falharia abismalmente nos comentários que eu produzi, e qualquer método projetado para reconhecer meus padrões de comentários falharia abismalmente no seu.
cmaster 6/07
@ master Ah, entendo, acho que não entendi a pergunta. Forneci uma maneira simples de formatar os comentários de forma que eles possam ser facilmente analisados ​​quanto ao tipo, o que não foi solicitado.
IanF1 6/07
2

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.

Martin Maat
fonte
2

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.

gnasher729
fonte
1

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.

Graham
fonte
-3

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.

jamesqf
fonte
Há também #ifdef __DEBUG ... #endif, ou qualquer definição personalizada que você deseja usar. __DEBUGé bom, porque muitas vezes você só precisa alterar a configuração do projeto para obtê-lo. Mas a maioria dos IDE também permite que você defina suas próprias configurações, o que pode fornecer qualquer coisa nesse local.
AaronD 8/07
O que você quer dizer com "código de teste"? Testes unitários? Eles não devem ser comentados, devem ser mantidos no conjunto de testes e executados o mais rápido possível, independentemente de alguém achar necessário. Claro, é fácil voltar a comentar um pedaço de código, mas é ainda mais fácil não fazer nada e ter o conjunto de testes já em funcionamento ...
leftaroundabout 08/07
11
Argh, não faça isso. Comentar o código "para testar algo" funcionará perfeitamente 99 em 100 vezes ... e, no único caso, você esquecerá de removê-lo (se não for mais necessário) ou - ainda pior - esqueça de descomentá-lo ( se for necessário) e as coisas podem ficar feias.
CharonX 8/07
@leftaroundabout: Não, quero dizer coisas como as declarações printf colocadas para verificar valores.
jamesqf 8/07
@ jamesqf, você nunca deve precisar desse tipo de coisa, é para isso que existe um depurador. Mas mesmo que você use printf/ coutou similar para obter o código recém-escrito corretamente (o que eu admito que já fiz antes), não é realmente muito eficaz deixá-los lá. Se alguém quiser fazer alterações e souber sobre quais variáveis ​​eles precisam de informações, é rápido e fácil escrever o printfnovo, enquanto se esse desenvolvedor não souber o que é necessário e apenas desmarcar todas essas printfdeclarações, a enorme faixa de texto em o terminal provavelmente também não os ajudará.
leftaroundabout