Esta profesión está llena de temas controvertidos, temas que unos ven de una manera y otros desde un lado totalmente opuesto. Te habré contado decenas de estas en estas páginas y hoy voy con otra que hemos tocado en ocasiones de manera más indirecta de lo que lo vamos a hacer hoy… los comentarios en el código.
Hoy no voy a hablar de documentación en general, que ya le hemos dedicado post como Taller de desintoxicación documental y superación de la abstinencia del word y powerpoint, sino específicamente de los comentarios en el código.
Se dice que ver comentarios en el código no es “estrictamente un mal olor, es más bien un desodorante”. Porque lo que ocultan los comentarios muchas veces es el mal olor que desprende alguna mala práctica de programación que debería llevarnos a reflexionar… ¿por qué algo necesita ser explicado y no es auto explicativo?
Quizás el texto más famoso sobre el problema de los comentarios en el código es de Beck y Fowler y sus “bad smells” (“malos olores”), capítulo 3, donde viene una recopilación de cosas que “huelen mal” y de las cuales ya te hablé en su día en Alguna reflexión sobre el conocimiento en ingeniería del software y una lista de malos olores (del 2011) y traté alguna, como aquella de Duplicar, o copy pegar, código no es una buena idea o esa de “Un case o switch con muchas cláusulas, o muchos ifs anidados, tampoco es una buena idea”. Bueno, pues entre esos malos olores están los comentarios.
La idea del posible problema de los comentarios se dice rápido… pueden enmascarar algo que se ha programado mal y que como no se entiende hay que tirar de lenguaje natural para explicarlo.
De hecho, debe haber miles de chistes, anécdotas, memes, etc., sobre comentarios de lo más absurdos que se pueden encontrar en el código.
Más importante aún en un modelo de trabajo ágil
Que la importancia de controlar los comentarios debiera ser igual en un modelo de trabajo no ágil, pero si estás en un modelo ágil tomán si cabe más importancia su control (o el control de las malas prácticas que pudieran enmascarar).
Uno de los modelos ágiles que más lo trata es eXtreme Programming. Si en agilidad asumimos como bienvenido el cambio, si los “planes” son cambiantes, el producto… debe estar también preparado para el cambio.
Y que un software esté preparado para el cambio implica un montón de buenas prácticas, de las que, para no extender el post, destaco, diseño simple, que se pueda refactorizar sin alto coste y complejidad y pruebas unitarias.
Los comentarios en el código pueden ser síntoma de que faltan muchos de los anteriores, en especial el diseño simple.
Lo que mides, y premias, es lo que obtienes
Curioso es como durante años, en muchos sitios, incluso aún hoy, con esto de los comentarios ha sucedido como con medir en “horas” (recuerda Horas en la oficina vs ideas y conocimiento aportado). Se pedía a la gente que echara horas, y se le media por ello, sin que ello fuera garantía de aporte de valor. De igual manera, se pedía a los programadores incluir comentarios en el código… sin que ello garantizara buenos desarrollos.
Ya sabes lo que mides lo que obtienes, si mides comentarios obtienes código comentado, que no necesariamente bien programado.
Primera vez que me tocó hacer una gestión Ágil en una empresa... año 2001. Desde entonces he trabajado en, o para, más de 90. Y he formado a más de 2000 alumnos.
También soy profe de la Universidad Rey Juan Carlos.
- Las 3 matrices de priorización Ágil - 19 octubre, 2023
- Etapas del Agile Product Management - 12 octubre, 2023
- Agile Product Management: DINÁMICA «Árbol Solución Oportunidad» + «Valores Esperados» - 5 octubre, 2023
Muy interesante, como siempre, el post.
A mí, sin embargo, «me huele» a que la gráfica valor vs código tiene forma de campana: algo hay que tener, pero no pasarse escribiendo un Quijote.
Eliminar comentarios implica (a) que hay nivel muy alto de madurez en las prácticas de codificación y (b) que también hay un diseño y arquitectura software de relaciones entre componentes software que tiene también estabilidad y madurez.
Y, lo más difícil: establecer métricas concretas que demuestre que da más valor no comentar que su contrario… Sobre todo, en desarrollos subcontratados.
Personalmente opino que el coste de no comentar es menor que el coste de tener a un nuevo programador que no necesite comentarios. Es decir, «mejor coméntalo, que el nuevo que entre se entere».
Sin comentarios…
/**/
Acertado este post. Cuando un buen código no dberia requerir de amplias explicaciones ya que al estar bien diseñado y adecuadamente factorizado debería cumplir sus objetivos clara y puntualmente. Lo anterior me lleva al punto sensible de estándares de codificación que forma parte de un código transsparente y entendible. Tieenes algún estándar favorito??? Hay quiees defienden la opinión de que cada ccompañia genere el propio de acuerdo con sus necesidades. Que opinas??? Un saludo.
Any fool can write code that a computer can understand. Good programmers write code that humans can understand. Martin Fowler, 2008.
…y sin embargo, acostumbrado durante años a documentar los proyectos, objeto a objeto, función por función para proyectos en equipo, he terminado por escribir, ahora que trabajo solo o en pareja lo que hace las funciones en los propios ficheros de código en forma de comentarios para luego ir intercalando el código. Es una forma de diseñar sin usar docxml, latex o el paquete de oficina de toda la vida. Finalmente voy limpiando porque me molestan al visualizar el código pero en ocasiones se quedan algunas líneas por olvido o por pura estética. Y sí, el código debe ser auto explicativo, pero no hay que demonizar los comentarios.
Si el código se lee fácil, no hacen falta comentarios.
Si te hacen falta comentarios, deberías preguntarte: por qué mi código no se lee fácil?
Normalmente es una cuestión de no saber trabajar el nivel de abstracción. Lo que provoca que tengas un método con varios niveles de abstracción mezclados y además muy largo.
Un método público de lógica de negocio debería estar formado por un código muy corto (debe verse en pantalla sin hacer scroll), claro, con un nivel de abstracción alto y apoyado en métodos privados con nombres de mucha semántica y donde el nivel de abtracción ya si es más bajo.
De esta forma, el método público se lee muy fácil porque está casi escrito en pseudo código.
Entonces los comentarios se quedarían para explicar decisiones o circunstancias que afectaron al diseño (disclaimers).
Esto para lógica de negocio. Si lo que estás programando es un api, librería, framework, etc., entonces si que conviene documentar cómo y para qué se usa cada clase y método (si es posible con ejemplos).