En un artículo anterior, hablamos sobre la importancia de los comentarios en el desarrollo de software.
Aunque son herramientas poderosas para mejorar la legibilidad de nuestro código, debemos usarlos con cuidado. Un buen comentario puede hacer el código más fácil de entender, pero uno malo puede perjudicar tu productividad.
Los comentarios malos saturan tu editor y hacen el código más difícil de navegar y formatear. Los comentarios extremadamente verbosos son imposibles de mantener y se degradan fácilmente después de un par de meses. El tipo más peligroso, sin embargo, es el comentario con información falsa: te desinforma y te impide tomar las decisiones correctas.
En este artículo, exploraremos algunas de las formas más comunes de comentarios que debes evitar.
Comentarios engañosos
El código va a cambiar, es algo natural que puedes esperar en cada proyecto de software.
A veces, la lógica de tu programa cambiará de una manera que hará obsoleto un comentario. Perderá contexto y se volverá sin sentido. Si encuentras un comentario que es obviamente incorrecto, puedes eliminarlo de manera segura o actualizarlo.
A veces, el cambio será más sutil, y no será obvio que el comentario ya no aplica más. Este tipo de comentario es particularmente peligroso porque te lleva a asumir cosas que ya no son ciertas. Si basas tu implementación en esta información desactualizada, la posibilidad de introducir nuevos errores en tu código es peligrosamente alta.
Es muy difícil protegerte contra este problema. Solo hay dos maneras de garantizar que esto no suceda:
- No escribir comentarios en absoluto: Un poco lamentable, ya que sabemos que algunos comentarios son genuinamente útiles.
- Siempre actualizar los comentarios para reflejar la realidad de nuestro código: Esto sería ideal, pero en la práctica es poco probable que suceda a menos que seas la única persona trabajando en el proyecto.
La solución es comentar solo las cosas que importan, y si uno de nuestros comentarios restantes se vuelve inválido, actualizarlo inmediatamente.
Comentarios de bitácora
Mantener un registro en la parte superior de cada archivo solía ser una forma popular de hacer seguimiento de los cambios. Afortunadamente, ahora tenemos sistemas de control de versiones que se encargan de esto de una manera mucho más eficiente y limpia. Si tu código aún no está bajo control de versiones y todavía mantienes registros en cada archivo, prueba cualquier VCS, vale totalmente la pena.
// JUN 7 2007: Agregué nueva funcionalidad: Los perros pueden ladrar en 3 idiomas diferentes
// FEB 20 2007: Agregué soporte para gatos, ¡ahora nuestros perros pueden incluso ser gatos!
// FEB 7 2007: Salí a almorzar con Robert, me pregunto si le gusto...
// JAN 22 2007: Agregué soporte multihilo, este es un perro realmente eficiente ahora
// JAN 13 2007: Agregué atributos geniales
// JAN 8 2007: Creé la versión inicial de esta clase
public class Dog{
// Implementación de la clase
}
Comentarios del capitán obvio
Este tipo de comentario no agrega ninguna información importante, solo está ahí para saturar tu pantalla.
Si tu lugar de trabajo tiene una política de ‘número mínimo de comentarios por clase’, estoy dispuesto a apostar que como el 90% de los comentarios que escribes pertenecen a esta categoría.
Este es el tipo de comentario que escribes solo porque, bueno, necesitas comentar tu código, ¿no?
Recortar lo innecesario y remover distractores es una habilidad importante en nuestra profesión. Hazle un favor a tu equipo y elimina los comentarios que solo establecen lo obvio.
public class Dog{
private String name;
// Constructor por defecto--OBVIO
public Dog() {
//Establece un nombre por defecto - OBVIO
name = "Laika";
}
// Otro constructor que establece el nombre durante la construcción - OBVIO
public Dog(String dogName){
name = dogName;
}
// getter para el atributo nombre - OBVIO
public String getName(String dogName){
name = dogName;
}
}
En el ejemplo de código de arriba, puedes eliminar cada comentario. En lugar de hacer la clase más difícil de entender, esto la hará mucho más fácil de leer. Los comentarios malos son una distracción. Elimina los distractores que solo establecen lo obvio y no proporcionan información valiosa.
Redundancia de atributos de una línea
¿Alguna vez has visto una clase como esta?:
public class Dog {
// La edad del perro
private int ageInYears;
// El peso del perro
private int weight;
// El nombre del perro
private String name;
// La raza del perro
private String breed;
// Implementación de la clase
}
Esos comentarios son inútiles, no agregan información importante. Es más, los nombres de los atributos ya me dan más información que esos comentarios: ¡ageInYears incluso me dice la unidad!
El único comentario que agregaría sería una aclaración de que el peso del perro (en realidad es masa, pero entiendes) está en kilogramos o libras. Pero algo incluso mejor sería cambiar el nombre de la variable a massInKg o massInPounds.
Este tipo de comentario en la sección de atributos de una clase es bastante común, especialmente entre desarrolladores principiantes. Deja de escribirlos y en su lugar trabaja en darle a cada variable un gran nombre.
Usar comentarios como marcadores de corchetes
Esto es algo que solía hacer mucho.
Al escribir código, a veces encontramos estructuras anidadas dentro de bucles y condicionales. Saber qué corchetes van juntos es un poco difícil si la estructura es lo suficientemente compleja, ¿la solución? Escribir comentarios junto al corchete de cierre para marcarlo.
Esto es inútil ahora que tenemos editores de texto e IDEs que resaltan los dos corchetes que van juntos. Otra razón para no usarlos es que, si tu código anidado es tan complejo, podrías beneficiarte de reescribir el código y crear funciones para las sub-operaciones. En lugar de esto:
for(...){
//....
//....
//....
if(...){
//...
//...
for(...){
//...
//...
//...
//...
}//for interno
//...
//...
}//if grande
else{
//...
//...
if(...){
//...
//...
//...
//...
}//if pequeño
else{
//...
//...
//...
//...
}//else pequeño
//...
//...
}// else grande
}// for externo
Podrías querer escribir algo como esto:
for(...){
function1();
if(...){
function2()
}else{
function3()
}
}
function1(){...}
function2(){...}
function3(){...}
O, dependiendo del caso, descomponer esa estructura aún más.
Comentar el código para deshabilitarlo
Esta es una práctica extremadamente común: en lugar de eliminar el código por completo, simplemente deshabilitarlo con un comentario.
Esto sucede porque pensamos que algún día este código será útil otra vez. O porque (Dios no lo quiera) comentar y descomentar código para diferentes despliegues es la forma en que manejamos diferentes sistemas.
Si el código no debería estar ahí, elimínalo. Es una experiencia liberadora limpiar tu software de todas esas líneas muertas. Porque la mayoría de nuestros proyectos tienen alguna forma de control de versiones, no tienes que tener miedo de perder ese código. Ve y recorta lo innecesario, tu proyecto se sentirá mucho más limpio después.
Documentación API para métodos privados
Documentar la interfaz pública de tus clases con formato de documentación especial es bastante útil. Puedes usar herramientas como Javadoc o YARD para generar automáticamente documentación útil sobre cómo usar tus clases.
Los métodos privados son un asunto diferente: al usuario de tu biblioteca no le importa (y no debería) conocer los detalles de implementación de tu clase. El ocultamiento de información es una característica extremadamente poderosa que libera tu cerebro de la información que no necesita. Escribir documentación pública para estos métodos es una forma de violación del ocultamiento de información.
Así que, mantén la documentación de interfaz pública para métodos públicos, esos son los que les importan a los usuarios.
Escribir buenos comentarios es difícil
Escribir comentarios es una habilidad similar a escribir buenos nombres de variables. Los principios son muy similares también: quieres comunicar información relevante sin saturar tus archivos. Un buen comentario es tanto conciso como informativo, igual que un buen nombre de variable.
Ve y practica escribir comentarios, y también practica eliminarlos. Refactoriza tu código para hacerlo obvio al lector: elige buenos nombres de variables, escribe funciones pequeñas bien definidas, usa estructuras de control obvias. Si haces de la calidad de tu código una prioridad, necesitarás muchos menos comentarios y tus colegas estarán más felices de trabajar contigo.
Usa los comentarios sabiamente y trata de hacer que cada uno de ellos cuente.
Qué hacer después:
- Comparte este artículo con amigos y colegas. Gracias por ayudarme a llegar a personas que podrían encontrar útil esta información.
- Puedes encontrar más información sobre crear buenos argumentos de función en el capítulo 4 de Clean Code.
- Envíame un email con preguntas, comentarios o sugerencias (está en la página Autor).