Cómo utilizar cuidadosamente los comentarios de código en JavaScript

Pocas cosas dan más dolores de cabeza a los programadores que leer el código de otras personas, pero de hecho, leer el propio código también puede resultar insoportable durante mucho tiempo. El problema no es el código en sí;

Los comentarios necesarios pueden ahorrarle tiempo a usted y a otras personas al aclarar los detalles de implementación y la intención del diseño. Sin embargo, las anotaciones a menudo pueden ser contraproducentes; por ejemplo, demasiadas anotaciones generadas automáticamente pueden distraer a los lectores, o las anotaciones obsoletas e inválidas pueden engañar a los lectores.

Comentarios generados automáticamente

La proliferación de comentarios de código debe haber comenzado con IDE como Eclipse y Visual Studio. Estos IDE proporcionan numerosos atajos para generar esqueletos de clases/interfaces, propiedades con Getters/Setters, etc. Si ha utilizado un entorno de desarrollo integrado, el siguiente código le resultará familiar:

/**

* @param args

*/< / p>

public static void main(String[] args) {

//TODO código auxiliar de método generado automáticamente

}

Las seis líneas anteriores Cuatro comentarios en el código no contienen información, ni explican cuáles son los parámetros args ni qué hace main. Sin embargo, una gran cantidad de proyectos están llenos de anotaciones generadas automáticamente.

Recomendación: Si hay parámetros o mecanismos que necesitan explicación, agregue esta información. De lo contrario, elimine los comentarios generados automáticamente. Excepto, claro está, para generar documentación.

Anotaciones excesivas

Siempre hay personas que se esfuerzan mucho en escribir notas largas, detalladas, oscuras o dóciles. En pocas palabras, un comentario que no me ayuda a leer el código más rápido es un comentario fallido.

Para ilustrar este punto, Harttle clonó el código fuente del kernel de Linux 4.x y realizó un análisis superficial de sus líneas comentadas. Sabemos que más del 95% del código del kernel está escrito en C, por lo que contar los archivos .c es suficiente para ilustrar el problema. linux git:(maestro) git clone git@github.com:torvalds/linux.git --profundidad=1 linux git:(maestro) buscar .-nombre "*.c" -o -nombre "*.h"-exec grep -E '^\s*((\*)|(/[/*]))'{}| wc -l

724804 linux git:(maestro) buscar .-nombre "*. c" -o -name "*.h"-exec cat {}| wc -l

4018961linux git:(maestro) nodo

> 724804/(4018961-724804)

0.22002715717556875

El repositorio del kernel contiene aproximadamente 4,02 millones de líneas de código (las líneas vacías no se eliminan), de las cuales 720.000 líneas, o el 22%, son comentarios. El kernel de Linux está escrito en C de bajo nivel e implica controladores, gestión de memoria y programación de CPU complejos. Por lo tanto, habrá más comentarios y los comentarios de proyectos generales deberían ser menores que este valor.

『Sugerencia』: Si más del 20% de tu código está comentado, entonces obviamente tienes demasiados comentarios.

Comentarios de encabezado de archivo

Muchos editores/IDE generarán encabezados de archivo predeterminados, por ejemplo:

/**

* @ file /tmp/xxx.js

* @autor harttle(yangjvn@126.com)

* @fecha 2016-08-30 22:33

* @description Una implementación de XXX para XXX.

*/

Los comentarios del encabezado del archivo enumeran claramente el autor del archivo, la descripción funcional y otra información que parece útil. Sin embargo, el problema con este encabezado es su facilidad de mantenimiento:

Otros pueden no cambiar @author cuando hacen pequeños cambios, e incluso @author puede no darse cuenta de que el archivo ahora es completamente diferente.

¿Necesita gastar energía actualizando la información de @file cada vez que mueve un archivo?

¿Quién recordará actualizar la @descripción después de cada cambio de código, y la @descripción siempre es engañosa?

Los comentarios del encabezado tienen como objetivo mantener metainformación sobre el archivo de código para que pueda utilizarse al publicar y mantener los derechos de autor del autor y otra información durante el proceso de implementación. Sin embargo, en un repositorio controlado por versiones, esta información ya no necesita mantenerse manualmente, e incluso puede ver la información del autor y la hora de cada línea de código a través de git culpable.

"Recomendación": Utilice una herramienta de control de versiones para eliminar los comentarios del encabezado. La información de derechos de autor se puede generar en el momento de la compilación o del lanzamiento.

Comentarios redundantes

El código con intenciones muy claras no necesita comentarios y los comentarios redundantes pueden causar problemas de mantenimiento. Especialmente los escritores no ingleses caen a menudo en este malentendido. Por ejemplo, comentarios sobre variables y funciones:

/*

* GetUserCount

función getUserCount(){

// Lista de usuarios

var userList = [];

}

¡Esto es una tontería! !El problema con los comentarios redundantes todavía radica en el mantenimiento, por ejemplo, cuando ajustamos la funcionalidad de la función, reorganizamos los parámetros o cambiamos los nombres de las variables, tenemos que actualizar los comentarios. De lo contrario, estas notas engañarán al próximo lector.

Sugerencia: No digas tonterías.

Extraer comentarios como identificadores

Quizás hayas tenido la experiencia de escribir un gran fragmento de código y dividirlo en fragmentos. Luego agregue comentarios al comienzo de cada bloque de código.

Por ejemplo:

función calcTotalCharge(películas, usuario){

// Calcular el costo de la película

var movieCharge = 0;

para ( var i=0; i

var charge = 0;

var movieCharge = 0;

for (var i=0; i

carga = película.carga * 2;

}

else if (movie.type === 'normal'){

carga = movie.charge;

}

movieCharge += carga;

}

// Calcular tarifas de usuario

var rentCharge = 0;

if(user.isVIP1){

rentCharge = 10;

}

if(user.isVIP2){

alquilerCargo = 200;

}

más si(usuario.isVIP3){

alquilerCargo = 300;

}

más si(usuario.isVIP4){

rentCharge = 500;

}

// Calcular el costo total

devolver movieCharge + rentCharge;

}

Los tres comentarios en el código anterior aceleran la lectura del código, pero siempre que el código requiera la lectura de comentarios, debemos ser claramente conscientes de que hay un problema con la estructura del código.

Para el código anterior, podemos usar una estructura más reutilizable para eliminar los comentarios:

función calcTotalCharge(películas, usuario){

return calcMovieCharge(películas) + calcUserCharge(usuario);

}

función calcMovieCharge(películas){

var total = 0;

for(var i= 0 ; i

total += calcSingleMovieCharge(película);

}

devolver total;

}

función calcSingleMovieCharge(película){

if(movie.type == == 'descuento') return movie.charge * 0.8;

else if (movie.type === 'corto') devuelve movie.charge * 2;

else if(movie.type === 'normal') devuelve movie.charge;

devolver 0;

}

función calcUserCharge(usuario){

si(user.isVIP1) devuelve 10;

si no (user.isVIP2) devuelve 200;

de lo contrario, si (user.isVIP3) devuelve 300;

de lo contrario, si (user.isVIP4) devuelve 500;

devuelve 0 ;

}

Después de refactorizar el código, los comentarios pierden sentido. La intención del código se expresa claramente en la denominación de los identificadores. Normalmente, la refactorización reduce la cantidad de código porque las ramas están encapsuladas y la lógica de cada unidad es más clara.

Recomendación: Cuando nos vemos obligados a realizar anotaciones, debemos ser conscientes de que puede haber algún problema con el diseño estructural.

Comentarios útiles

Harttle ha descrito tantos antipatrones hasta ahora, por no decir que los comentarios del código no son importantes. Más bien, se trata de afirmar que "los comentarios del código existen para ayudar a comprender el código mismo". Por ejemplo, los comentarios se vuelven muy importantes al escribir trucos, polyfills, código ad hoc y algoritmos complejos. Por ejemplo:

Truco y Polyfill. A veces, un simple truco puede resolver la mayoría de los problemas, por lo que no es necesario escribir algoritmos complejos de Polyfill, como verificar la compatibilidad con la API DOM del navegador, verificar el entorno AMD/CommonJS, etc. En este punto, debemos hacer explícita la intención del truco e incluso extraer el código en un módulo polyfill.

Algoritmos complejos. A veces los algoritmos que escribimos son tan matemáticos que son fáciles de entender de un vistazo. Si la intención de estos algoritmos queda clara antes de comenzar, el lector no tendrá que esforzarse mucho en leer las matemáticas.

Interfaz pública. La interfaz externa de un módulo define lógicamente el tipo de módulo y el código de la interfaz pública es más fácil de leer. Esto es especialmente cierto para las interfaces JavaScript: si no anota el contenido específico en las opciones, quién sabrá cómo se usa la interfaz.