¿Existe algún método para diferenciar los comentarios informativos del código comentado?

Durante el transcurso de la programación, terminarás con algunos comentarios que explican el código y algunos comentarios que eliminan el código:

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

¿Existe un buen método para analizar rápidamente cuál es cuál?

He jugado con el uso de 3 /y /** */para comentarios descriptivos.

También he usado un complemento VSCode para resaltar //TODO:y//FIXME:

Hay una solución muy simple para esto: eliminar el código comentado.

Realmente, solo hay dos buenas razones para comentar el código: para probar algo / hacer una solución, o para guardar el código que podría usar más adelante. Si está probando o arreglando algo, elimine el código comentado tan pronto como haya terminado con la prueba o la corrección. Si está guardando el código que podría usar más tarde, conviértalo en un código de primera clase y póngalo en algún lugar, como una biblioteca, donde se pueda utilizar.

Agregando a la excelente respuesta de @ RobertHarvey, creo que solo hay una razón legítima que he encontrado para guardar el código comentado en el control de origen, incluso temporalmente: en caso de código de reemplazo no obvio que no debería o no puede usarse en este momento por alguna razón . Incluso entonces, la mayor parte del comentario debería ser la explicación, no el código de reemplazo. Esto podría ser un error o una característica del lenguaje que aún no se considera estable. Podría verse más o menos así:

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

En este caso, el trabajo ya se ha realizado, pero aún no puede aprovecharlo, por lo que eliminarlo significa que alguien tendría que redescubrirlo más tarde. Lo mismo ocurre con soluciones subóptimas que pueden parecer superiores a primera vista o compensaciones conscientes contra soluciones similares .

Precaución: no ensucies tu código con soluciones alternativas. Cada tarea se puede hacer de infinitas maneras diferentes, y no es rentable explorar este espacio durante mucho tiempo para cada cambio. Las revisiones de código pueden ser un buen lugar para descubrir esos comentarios faltantes, cuando su colega sugiere una mejora que ya ha descubierto que no es óptima.

Hmm, leí esta pregunta un poco diferente de Robert, quien afirma correctamente que el código comentado debería eliminarse.

Sin embargo, si está buscando una convención para marcar el código para su posterior eliminación, un viejo favorito mío es:

//b = false; //TODO: remove

Algunos //TODO:comentarios de bandera del IDE o se les puede enseñar. Si no, generalmente es una cadena de búsqueda. Es mejor seguir cualquier convención que su tienda haya establecido porque esto se puede hacer de varias maneras. Cada código base debe hacer esto de una manera. Lo mantiene investigable.

analizar rápidamente cuál es cuál?

Sin esa marca, la forma automática de hacerlo es con el compilador. Si quitar el comentario produce un código que se compila, debe haber sido un código comentado. Escribir un complemento IDE que compruebe que no sería difícil. Pero dejará atrás el código comentado con errores.

Es por eso que es mejor marcar simplemente el código comentado como código en el momento en que lo comenta. Esto le permite trabajar de manera no destructiva mientras decide si realmente quiere que desaparezca. Como todos somos interrumpidos y somos algo olvidadizos, no se sorprenda si algunas líneas se registran mientras están en ese estado. Si lo hacen, es bueno que al menos estén claramente marcados y se puedan buscar. Las macros de teclado me han ayudado con esto en el pasado. Es difícil que te interrumpan en medio de esto si puedes hacerlo con una sola pulsación de tecla.

Puede llevar esto hasta el punto de consagrar la marca en sus pruebas de integración continua. Vaya, estoy tratando de registrarme con TODO pendientes nuevamente.

Utilizo directivas de preprocesador para eliminar código, no comentarios en absoluto:

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

Esto hace que sea muy fácil de buscar, y mi resaltador de sintaxis lo trata como un comentario. Incluso puedo colapsarlo en una sola línea:#if FALSE(...)

Puede ampliar esa idea para tener varias opciones:

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

Y comprobación de errores en tiempo de compilación:

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

Por supuesto, no quiere exagerar en esto, o se hace difícil saber qué se está compilando realmente y qué no. Pero se entiende la idea, y de todos modos es el mismo problema que para el código comentado ... siempre que solo lo use estáticamente. Si sus condiciones son dinámicas, es peor.

Para determinar cuál es cuál en una base de código existente que no consideró este problema en absoluto, no creo que haya una solución universal. Tendrá que buscar patrones usted mismo y probablemente codificar una expresión regular para encontrarlos.

Estoy de acuerdo con la respuesta que indica que el código antiguo debe eliminarse en lugar de comentarse cuando sea posible, sin embargo, he observado una convención para las pocas ocasiones en que se necesita un código comentado.

(Mi base es C # pero esto se puede aplicar a cualquier lenguaje de sintaxis C, por ejemplo, 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();
//}

Todavía estoy interpretando la pregunta de manera diferente, pensando que quieres encontrar el código comentado.

El código de estilo C seguramente tendrá punto y coma, mientras que es poco probable que los comentarios tengan punto y coma. Entonces, para el código comentado de una sola línea, puede usar esta expresión regular:

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

Para el código comentado de varias líneas, podría ser

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

Tenga en cuenta que Visual Studio es un poco peculiar sobre los saltos de línea en las expresiones regulares, no cuentan como espacios en blanco, debe especificar un \ n explícito.

Si usa un editor con un compilador que se ejecuta en segundo plano (como Xcode y Clang), puede intentar compilar el texto del comentario. Por ejemplo, "una descripción concisa" da errores, "b = falso;" no. A continuación, puede utilizar diferentes resaltados de sintaxis.

Un método más simple sería un complemento IDE que use algunas heurísticas, como palabras múltiples en una fila que no sean palabras clave, puntos para comentarios, coincidencia con punto de rizado para código, etc.

Otras respuestas han cubierto variaciones sobre el tema "no comentar código". Pero a veces todavía lo quieres como referencia.

Si realmente necesita el código para quedarse, una mejor solución es rodear el código con "#if 0 ... #endif", idealmente con un comentario para decir por qué. Esta es la estrategia recomendada de varios estándares de codificación, incluido MISRA.

Simple, al menos para mí, y en C / C ++. Los comentarios incluidos en / * * / son informativos. El código de prueba que se elimina temporalmente se comenta con //.

Y hay buenas razones para dejar el código de prueba en el archivo pero comentado, al menos en el tipo de trabajo que hago. Tarde o temprano, alguien querrá hacer un cambio, que necesitará ese código. Descomentar un bloque toma un comando de editor, al igual que volver a comentarlo cuando haya terminado.