Poner comentarios en el código… ¿es una buena práctica o es típico en software de mala calidad?

Son tantos los temas, en el maravilloso mundo del desarrollo software, sobre los que podemos encontrar posturas tan separadas (véase, como uno de tantos ejemplos, aquello del diseño software: después de 60 años aún no sabemos si esencial o es inútil). Yo pienso que eso enriquece esta profesión. No es para menos, siendo una profesión que hoy mueve el mundo.
Uno de esos temas controvertidos es el uso de los comentarios en el código. Aparentemente, no debiera dar para tanto debate, pero sí que da: usar comentarios en el código ¿es una buena práctica o es típico en software de mala calidad?
Mientras escribo sobre este tema, no dejo de acordarme de aquellas maravillosas prácticas en la carrera, en Pascal, dónde teníamos que meter casi 30 líneas de comentarios en cada fuente, con el nombre, objetivo, versión, etc.
Pero aquello era en la Universidad, porque si revisamos qué dicen los principales nombres de la ingeniería software que han tratado el tema leeremos cosas como…

– Cuando sientas la necesidad de escribir un comentario, primero trata de refactorizar el código (te dejo una introducción al refactoring). K. Beck. en Refactoring.
– No documentes mal código – reescríbelo. Kernighan & Plauger
– «El uso adecuado de los comentarios compensa el fracaso para expresarte en el código. Ten en cuenta que he utilizado la palabra fracaso. Lo dije en serio. Los comentarios son siempre fracasos». Rober C. Martin en Clean Code: A Handbook of Agile Software Craftsmanship.
– ¿Qué el código no es legible sin comentarios? En casi todos los casos, se puede elegir mejores nombres de variables y mantener todo el código en un método en al mismo nivel de abstracción, para que sea fácil de leer sin comentarios. Sammy Larbi
– El valor de un comentario es directamente proporcional a la distancia entre el comentario y el código. A medida que aumenta la distancia, el comentario se convierte en engañoso, anticuado, o peor aún, incorrecto. Comentarios distantes son poco fiables. Jeff Atwood
– Buenos comentarios no repiten el código o lo explican. Aclaran su intención. Los comentarios deben explicar, en un nivel superior de abstracción al código, lo que estamos tratando de hacer. S. McConnell en Code Complete (un post sobre el libro)
Parece que existen bastantes voces críticas con el uso de los comentarios en el código. Pero, en cualquier caso, para los más humanos, para aquellos no dotados de tantas facultades, de conocimiento, o de tanto tiempo, para hacer buen software… que lo comenten un poco, por favor.

10 comentarios en “Poner comentarios en el código… ¿es una buena práctica o es típico en software de mala calidad?”

  1. Y no sólo comentar el código sino saber estructurarlo adecuadamente (o por lo menos seguir con la estructura que ya tenía). Yo programo en Java, y me gusta tener en mis clases los métodos agrupados por funcionalidades (getters y setters al final, arriba del todo los atributos cada uno con el comentario de lo que hace…). Luego llega alguien que tiene que mantenerlo y, para hacer un método nuevo, lo coloca donde les sale de las narices, rompiendo todo tu esquema. Ains….

  2. Pingback: Bitacoras.com

  3. Para mi (y como esto va de opiniones yo dejo la mía :D), el más acertado, o, mejor dicho, el que más se acerca a mi postura es:
    – Buenos comentarios no repiten el código o lo explican. Aclaran su intención. Los comentarios deben explicar, en un nivel superior de abstracción al código, lo que estamos tratando de hacer. S. McConnell en Code Complete (un post sobre el libro)
    EStoy de acuerdo en que muchas veces los comentarios no hacen más que repetir lo que el código nos dice, pero son útiles a la hora de explicar la funcionalidad que estamos implementando, o el porqué es necesario hacerlo así.
    Interesante post! (Como siempre 😉 )

  4. Yo comentarios usos los justos y necesarios:
    -Comentar algunas líneas de código complejas en cuando a que se han podido resumir en una línea lo que un programador novato haría en más de 5 líneas (lo típico del operador ternario ‘?’).
    -La documentación de un método, porque es importante que si un usuario va a usar determinada unidad, clase, …, sepa qué hace cada método.
    -Comentarios para la corrección de una práctica, para evitarme tener disgustos en revisiones.
    Saludos

  5. Desde mi punto de vista son fundamentales. Seamos serios y metodológicos. Precondiciones PostCondiciones fundamentales y si hay filigranas… se aclaran de forma concisa. Cuando te encuentras con código asi, ohh maravilla…. . Ser metodologicos es fundamental. Es mi opinión.

  6. Sólo puede haber una cosa más difícil que escribir tu propio código y es entender el que han hecho los demás. Y es que como somos personas normales nuestros programas están un poco lejos de lo que escriben Rober C. Martin, Plaugher o Kernighan, y escribimos código subóptimo y nos vemos en la necesidad justificar nuestras decisiones de diseño.
    Además, en la mayoría de las circunstancias, trabajamos con frameworks y bibliotecas que contienen errores, muchas veces no bien documentados, y que nos obligan a escribir código «extraño» a primera vista.
    Yo citaría también el trabajo de uno de los grandes de la Informática, Donald E. Knuth, sobre Literate Programming, donde se entremezclan las explicaciones con el código dando lugar a una singular unión de programa y del porqué del programa.

  7. Tengo una duda. La documentación en Java(De clases y métodos, p.e. «Esta clase bla bla» y los @param y @return de los métodos) se toman como comentario?? Igual estos están de más en los programas??

Deja un comentario

Tu dirección de correo electrónico no será publicada. Los campos obligatorios están marcados con *

Share This
Ir arriba