Malos comentarios
Los comentarios pueden ser una herramienta útil para explicar código complejo o el propósito de una sección. Sin embargo, en muchos casos, los comentarios son un síntoma de código poco claro o mal estructurado. En lugar de explicar el código con comentarios, el objetivo debería ser escribir un código autodescriptivo que sea fácil de entender sin necesidad de ellos.
1. Ejemplo Malo: Uso de Comentarios en Lugar de Nombres Claros #
El siguiente ejemplo muestra cómo un nombre poco descriptivo lleva a usar un comentario para explicar algo que debería ser obvio.
Código Malo #
Cargando actividad al acercarte…
2. Ejemplo Corregido: Nombres Claros #
3. Beneficios #
- Nombres Claros y Descriptivos: El nombre
carColordeja claro el propósito de la variable, eliminando la necesidad del comentario. - Mantenibilidad: Si se cambia el propósito de la variable, el nombre se actualiza, evitando comentarios desactualizados.
- Legibilidad: Cualquier desarrollador que lea el código entiende rápidamente de qué se trata sin necesidad de explicaciones adicionales.
En lugar de usar un comentario, podemos asignar un nombre significativo a la variable para que su propósito sea evidente:
Cargando actividad al acercarte…
Resumen del tema
Conceptos clave #
- Código Autodescriptivo: el código limpio debe expresar su intención por sí mismo; si necesitas un comentario para explicar qué hace una variable o función, es señal de que su nombre debe mejorar.
- Comentarios Redundantes: comentarios que solo repiten lo que el código ya dice añaden ruido visual y pronto quedan desactualizados.
- Cuándo Comentar: reservar comentarios para explicar el porqué de decisiones de diseño no obvias, advertencias técnicas o referencias a normativas externas.
Qué debes recordar #
No comentes código malo; refactorízalo y dale nombres descriptivos para que se explique por sí solo.