Cómo escribir comentarios de código correctamente: algunos ejemplos importantes
En este artículo, analizaremos algunos ejemplos simples de cómo escribir comentarios comprensibles en el código y por qué agruparlos
#TODO
Los desarrolladores utilizan este comentario para indicar la necesidad de una futura refactorización. El comentario #TODO permite señalar qué es exactamente lo que se debe agregar en esta parte del código y por qué es necesario.
// TODO switch to the jest when it will works with modules
import expect from 'expect';
import chalk from 'chalk';
solutionSlice: {
// TODO move counter to server
startTime: Date.now(),
processState: isFinished
? solutionStates.shown
: solutionStates.notAllowedToShown,
waitingTime,
},
# TODO Move to custom validator
validates :first_name, length: { maximum: 40 },
format: { with: UsefulRegexp.without_spec_chars },
allow_blank: true
#FIXME
La etiqueta #FIXME indica que se debe corregir algo en esta parte del código. En algunos casos, la funcionalidad de esta etiqueta se fusiona con #TODO, por lo que se recomienda usar #FIXME cuando se necesita señalar una parte del código que puede causar problemas en el futuro.
# FIXME: Esto se debe eliminar cuando se restaure la autenticación para las redes sociales
user_from_session = get_session(conn, :current_user)
// FIXME: esto es un truco con las rutas, deben ser reestructuradas
root: path.join(process.env.APP_DIR, '..'),
import/extensions: 0 # FIXME: remove when rule will be adjusted for new nodejs version
#Warming
Por el nombre de la etiqueta, se puede entender que si hay un comentario con una explicación del problema antes del código, se debe ejecutar ese código con mucho cuidado.
# Warning: The database defined as "test" will be erased and
#Error
Esta etiqueta indica un error en el código: el desarrollador puede explicar el problema y la razón por la cual no se pudo resolver. Por lo general, se deja un comentario con esta etiqueta cerca de la parte del código que no se ejecuta en absoluto o no pasa las pruebas.
Cómo aplicar correctamente las etiquetas
En cada IDE principal, hay complementos para trabajar con comentarios y agruparlos. Por ejemplo, en VS Code, la forma más común de trabajar con tales comentarios es el complemento Todo Tree, que crea un árbol de grupos de comentarios para trabajar eficientemente con ellos.
En las IDE de JetBrains, los comentarios #TODO y #FIXME se detectan automáticamente por el entorno de desarrollo en grupos de etiquetas unificadas. Para obtener más información sobre esto y cómo se puede ampliar la funcionalidad de esta característica a otros comentarios personalizados, puedes leer en el sitio web de JetBrains.
