Al organizar revisiones de código hace algún tiempo, cuando se trataba de problemas de legibilidad del código, la primera reacción de muchas personas fue agregar más comentarios. Y siempre siento que las anotaciones solo pueden ser la guinda del pastel, no un regalo en la nieve. Ninguna cantidad de comentarios puede cambiar el hecho de que la organización lógica del código es caótica, por el contrario, demasiados comentarios aumentarán el tiempo de lectura del código.
Nada es más útil que un comentario bien ubicado; nada estropea más un módulo que un comentario desordenado; nada es más destructivo que un comentario obsoleto y desinformativo.
Los comentarios son un mal necesario, solo cuando la expresividad del lenguaje de programación no es suficiente, necesitamos usar comentarios para explicar el significado del código. El uso adecuado de los comentarios es para compensar nuestra incapacidad para expresar la intención en el código. Si necesita escribir comentarios, piense si puede expresarlos en código.
Otra desventaja fatal de las anotaciones es que no son necesariamente correctas. Cuando vemos sus comentarios cuando modificamos el código de otras personas, tenemos una gran posibilidad de no modificar sus comentarios. Con el tiempo, el significado del código comentado ha cambiado, pero los comentarios no se han mantenido junto con el mantenimiento del código.
1. Los comentarios no pueden embellecer el código incorrecto
Una de las motivaciones comunes para escribir comentarios es la presencia de código incorrecto.
El código limpio y expresivo con unos pocos comentarios es mucho más fácil de leer y mantener que el código fragmentado y complejo con muchos comentarios.
2. Usa código para explicar
Por ejemplo, el siguiente código, cuál prefieres ver:
3. Buenas Notas
Algunos comentarios son necesarios y beneficiosos. Pero los únicos comentarios realmente buenos son aquellos que se pueden expresar sin comentarios.
3.1 Información legal
3.2 Notas que proporcionan la información necesaria
3.3 Interpretación de la intención
A veces, las anotaciones proporcionan no solo información útil sobre la implementación, sino también la intención detrás de una determinada decisión.
3.4 Interpretación
A veces, los comentarios traducen el significado de algún parámetro oscuro o valor de retorno en alguna forma legible. Por lo general, tratamos de hacer que el parámetro o el valor devuelto se exprese con suficiente claridad, pero si el valor devuelto o el parámetro es parte de una biblioteca estándar, no podemos modificar el código fuente, entonces podemos usar comentarios para explicar.
3.5 Advertencias
Se utiliza para advertir a otros programadores sobre las consecuencias de las excepciones.
3.6 Notas de Tareas
ToDo es un tipo de trabajo que los programadores creen que debería hacerse, pero por alguna razón aún no se ha hecho.
3.7 Ampliar
Se utiliza para amplificar la importancia de algo que parece irracional.
3.8 java doc de API pública
A menudo vemos este tipo de anotación en el código fuente de JDK y en el código fuente de Spring.
4. Malos comentarios
La mayoría de los comentarios son malos comentarios. A menudo, los malos comentarios son un apoyo y una excusa para un mal código, o una solución para una mala decisión, básicamente como si el programador hablara consigo mismo.
4.1 Murmurando
No tiene sentido agregar comentarios solo porque cree que debería o porque el proceso necesita agregar comentarios. Si decide escribir comentarios, tómese el tiempo necesario para asegurarse de escribir buenos.
4.2 Comentarios redundantes
Por ejemplo, el siguiente código:
Los comentarios no pueden proporcionar más información que el propio código.
4.3 Notas engañosas
Si los comentarios escritos no son lo suficientemente precisos, engañarán a las personas que lean el código.
4.4 Comentarios conformes
La llamada regla de que cada función debe tener un comentario de Javadoc o cada variable debe tener un comentario, a menudo hace que el código sea desordenado y, a medida que el código itera, si el comentario no se actualiza, confundirá la comprensión del código.
4.5 Comentarios registrados en diario
Alguien agregará un comentario al comienzo del módulo cada vez que edite el código.Este tipo de comentario es como una especie de registro que registra cada modificación. Una anotación como esta:
4.6 Notas de mierda
4.7 Marcadores de posición
A veces, a los programadores les gusta marcar un lugar especial en el código, como:
4.8 Notas después de paréntesis
4.9 Atribución y Firma
4.10 Código comentado
Es una mala práctica comentar el código directamente. Aquellos que mantienen el programa no se atreven a eliminar el código comentado, y el código comentado se acumula, lo que interferirá con la lectura del código, lo que no es propicio para el mantenimiento y la lectura del código.
4.11 comentarios HTML
4.12 Información no local
Si escribe un comentario, asegúrese de que describe el código más cercano.
4.13 Demasiada información
4.14 Conexiones no obvias
La conexión entre los comentarios y el código descrito debe ser obvia, al menos para que los lectores puedan ver los comentarios y el código y comprender lo que describen los comentarios.
4.15 Cabecera de función
Las funciones no necesitan mucha descripción, y un buen nombre para una función suele ser mucho mejor que un comentario en el encabezado de la función.
4.16 Javadoc en código no público
Javadoc es muy útil para las API públicas, pero es engorroso para el código que no se considera de uso público. No siempre es útil generar páginas de Javadoc para clases y funciones en el sistema, y los requisitos de formalidad adicionales de los comentarios de javadoc son casi equivalentes a los artículos estereotipados.
resumen:
- No utilice comentarios cuando pueda utilizar funciones o variables para describirlos.
- Si necesita agregar comentarios, primero considere si puede reorganizar el código y dar una función adecuada o un nombre de variable
- Los comentarios solo se agregan cuando es necesario.