Putting it together

by Luismi Cavallé

Para Martin Fowler, lo explica en Refactoring: Improving the Design of Existing Code, los comentarios actúan en bastantes ocasiones como desodorante de los malos olores de nuestro código. A menudo, un código abundantemente comentado se trata de un código de mala calidad. Los comentarios, la necesidad de los comentarios, ponen de relieve que nuestro código no es suficientemente sencillo, claro o expresivo.

La recomendación propuesta es: Cada vez que sientas la necesidad de comentar tu código, primero trata de refactorizarlo de manera que el comentario se haga innecesario. La mayor parte de las veces es posible.

Por ejemplo, si tienes un método muy largo en el que se realizan varias cosas y te parece que estaría bien comentar qué hace cada parte del mismo, tu problema es que tienes un método muy largo con más de una responsabilidad. Seguramente puedas extraer varios métodos, y buscarles nombres que sean autoexplicativos. Así no necesitarás comentarios.

El problema de los comentarios, además, es que finalmente no son más que documentación manual con los problemas que ya hemos mencionado otras veces: tienden a quedar desactualizados, nunca son del todo precisos por expresarse en lenguaje natural, etc. Con lo que buena parte de los argumentos en contra de la documentación puede aplicarse también en este caso.

Si bien es cierto que un mal código comentado siempre será mejor que un mal código no comentado, parece que en estos casos comentar el código es la solución “parche”, ya que no soluciona realmente, solo enmascara.

En un mundo ideal, en el que escribimos solamente código bonito, utilizando lenguages expresivos y siguiendo el principio de la menor sorpresa, nuestro código (junto a sus tests o specs) deberían ser completamente autoexplicativos.

En el MundoRealTM a veces no tendremos más remedio que comentar, pero más que para explicar el qué o el cómo, para explicar el porqué de un código que pueda resultar confuso o inesperado. Y no pasa nada, los lenguages nos ofrecen los comentarios para utilizarlos. Pero no abusemos de ellos, tratemos de mejorar nuestro código primero y seguro que no los necesitaremos tanto.

[Referencia al apunte que ha inspirado este]