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:
///
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.Respostas:
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.
fonte
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:
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.
fonte
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, afrobnicate
funçã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.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.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.
fonte
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.Uso diretivas de pré-processador para remover o código, sem comentar:
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:
E verificação de erros em tempo de compilação:
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.
fonte
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.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)
fonte
//
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.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:
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.
fonte
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.
fonte
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.
fonte
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.
fonte
#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.printf
/cout
ou 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 oprintf
novo, enquanto se esse desenvolvedor não souber o que é necessário e apenas desmarcar todas essasprintf
declarações, a enorme faixa de texto em o terminal provavelmente também não os ajudará.