Los comentarios en el código son basura

Ayer estuve viendo una presentación (en inglés) de Robert C. Martin (Uncle Bob) en la Øredev 2008 en la que trataba alguno de los contenidos de su nuevo libro “Clean Code” (Código Limpio) y uno de sus comentarios me hizo recordar a mi buen amigo (y tantas veces maestro) Xavi Gost cuando decía que los comentarios en el código son basura.

Efectivamente, según Uncle Bob, los comentarios son excusas para escribir un método y mentiras (porque casi siempre están desactualizados). Por ello nos pide que, para ayudar a mantener limpio nuestro código, los borremos sin ni tan siquiera leerlos. Obviamente no se refiere al javadoc, aunque bien podría hacerlo. Martin afirma que si en un método dado tenemos varios bloques de código separado por comentarios, eso está pidiendo a gritos ser separado en varias llamadas a métodos donde cada comentario será el nombre de cada método.

He de decir que, a pesar de lo radical que pueda parecer la propuesta de Mr. Martin, no puede tener más razón. De hecho, Xavi me contaba que él ha llegado a configurar su sistema de control de versiones para que eliminara todos los comentarios no javadoc antes de hacer efectivo un commit, con lo que, en la práctica, estaba empujando a los desarrolladores a no incluir comentarios en el código.

Muchos de los que han trabajado conmigo me habrán oido discutir durante horas sobre el nombre de una clase o de un método. Por ahí van los tiros. Tanto Martin en “Clean Code” como Beck en el imprescindible “Implementation Patterns” insisten en la vital importancia de que elijamos bien los nombres de clases y métodos porque son el primer paso para escribir un buen código. Haced la prueba, intentad escribir vuestro código sin comentarios y, cuando tengáis la intención de hacerlo, cambiarlo por una llamada a un método…

  • Juan

    Hola.

    Hace tiempo escribí algo sobre el mismo tema (http://agilizar.es/blog/24/10/2008/comentarios-en-una-refactorizacion-perfecta/) por una presentación en el OOPSLA’08.

    Yo no estoy de acuerdo del todo, la verdad. En principio suena bien, pero tomarlo al extremo, no. Escribir muchos comentarios está mal ya que hacer el código más ilegible cuando queremos justamente lo contrario. Sin embargo, en otros casos, unos mínimos comentarios son necesarios. Por ejemplo, una estructura donde los campos no son triviales, un algoritmo complejo, etc.
    No estoy hablando de escribir más comentarios que código, pero si el escribir una línea de comentarios ayuda a entender mejor el código, ¿por qué no usarlo?. No creo que absolutamente todo se haga entendible simplemente con buenos nombres y refactorización.

    En resumen, esta idea me parece ir de un extremo (usar comentarios por usar) al otro y, por regla general, ninguno de los extremos son buenos.

  • Jose Manuel Beas

    Lo siento, Juan, pero estoy del lado del Tío Bob (Robert Martin) porque mi experiencia refrenda su opinión: los comentarios terminan mintiendo (por falta de mantenimiento).

    Mi opinión:
    * si el campo no es trivial, quizás debería tener un nombre que lo hiciera comprensible (o un javadoc)
    * si el algoritmo es demasiado complejo, quizás debería refactorizarse para hacerlo más comprensible (o un javadoc)

    Creo que es mejor estar en este extremo que no en el medio porque además ayuda a automatizar la regla. Podemos hacer que el servidor de CVS o SVN (o lo que sea) limpie todos los comentarios y formatee todo el código del que se hace commit. Eso ayudaría a crear más aún el sentimiento de propiedad colectiva del código.

    Es mi opinión, claro.

  • Juan

    Lo sigo sin ver, José Manuel.
    JavaDoc también son comentarios, que automatizan la documentación, vale, pero te siguen diciendo que el parámetro tal es cual y pascual en el código. Lo mismo pero con algo de “azucar” añadido.

    Sigo pensando que ni tanto, ni tan calvo. Comentarios sí, los justos cuando den valor, y no cuando no aporten nada.

    Un ejemplo que se me acaba de ocurrir, seguramente no el mejor ni mucho menos. Supongamos una estructura algo así:

    struct binary_rules {
    uint type;
    uint size;
    uint offset;
    }

    El offset es la distancia desde el principio de la estructura hasta donde está la regla en sí (si te estás preguntando por qué no se usa un puntero, por ejemplo, supongamos que se lee de un fichero donde hay varias estructuras seguidas y los datos están al final por tema de optimizar la lectura y el acceso).
    Una manera sería poner un comentario “// desde el principio de la estructura” y otra sería cambiar el nombre a “offsetFromTheBeginningOfThisStruct”. La segunda también es una opcción válida, pero ¿es mejor que la primera o trae algún valor añadido?

    Por último, ¿por qué crees que el no tener comentarios da sensación de propiedad colectiva? y lo mismo pero al revés, ¿por qué el tener un comentario que dice “desde el principio de la estructura” quita sensación de propiedad colectiva?

  • Jose Manuel Beas

    Hola Juan,

    Dices que “Comentarios sí, los justos cuando den valor, y no cuando no aporten nada.”. Vale, pero lo que para uno da valor para otro puede ser confuso o incluso insuficiente. La regla tan estricta va más en el sentido de presionarnos para que busquemos buenos nombres a los métodos y variables, que refactoricemos cuando un método es tan largo que requiere bloques separados por espacios o comentarios, etc.

    Respecto a la propiedad colectiva. Creo que si forzamos un estilo en el formateo del código haciendo lo que comento en los “commits” (aplicando reglas de formato, quitando comentarios, eliminando espacios innecesarios…) el código queda más limpio y se pierde un poco la sensación de “éste código está tal y como lo dejé” y “nadie más que yo toca este código”, además del “feedback” que proporcionamos a los propios desarrolladores, que de manera casi inconsciente nos vamos acostumbrando al formato “oficial”.

    De todos modos, tanto en esto como en lo anterior, coincido contigo en que se trata de buscar un balance entre flexibilidad y valor, pero mis experiencias (quizás no hayan sido muy buenas) me indican que es mejor ser muy riguroso con la limpieza del código o de lo contrario la “suciedad” termina llenándolo todo.

    Por cierto, Juan, muchas gracias por tus comentarios porque un poco de debate obliga a explicar conceptos que de otra manera pueden quedar poco claros y eso siempre es enriquecedor.

  • Juan

    Hola.

    Lo mismo se puede decir del nombre del método o del tipo de refactorización. Es decir, yo puedo hacer una refactorización o poner un nombre a una variable y tú puedes pensar que hay mejores formas o nombres (o incluso que no te llegue a quedar completamente claro por qué lo he hecho así).

    En cuanto a lo del formateo del código estoy de acuerdo y me parece una buena idea. Pero ten en cuenta que formateo y comentarios son cosas distintas. Una cosa es estandarizar al formato elegido en todos los commits y otra muy distinta borrar todos los comentarios. Yo sólo difiero y veo un poco “extremista” lo segundo, no lo primero.

    Como en muchas otras cosas hay que usar el sentido común y pensar qué es lo mejor en cada situación.
    Lo que no me gusta es tener una regla extremista que en algunos casos puede conllevar el resultado contrario al que se espera si se sigue religiosamente.
    Y esto no significa que no esté a favor de las buenas refactorizaciones ni de los buenos nombres de los métodos, clases, variables y constantes. Simplemente una cosa no quita la otra.

    Lo mismo digo, JMB. Es más, deseando estoy que llegue el sábado para conocernos en persona en la reunión “re-fundacional”.

  • Yo comento fácilmente menos del 1% de las líneas. A veces es necesario, ya que si invocas un método de una API cuyos nombres no controlas, por ejemplo, puede no quedar clara la intención. Pero, en general, coincido con la teoría de no comentar y con la de quitar comentarios cuando copio código de internet. Hay que reformatear y refactorizar hasta que quede claro sin comentarios.

  • Además, los comentarios no compilan. Eso puede ser una razón de peso. ¿No?

  • Curioso que ohloh.net valore que cuantos más comentarios mejor…