Mi cruzada contra los comentarios en el código

Los que me conocéis sabéis que soy un rabioso defensor de mis principios, lo cual no quiere decir que mis ideas estén escritas a fuego, dicho sea de paso.

Lo que me trae por aquí hoy es algo que me toca especialmente las narices: Los comentarios en el código.

Lo reconozco, al principio era un ávido comentador de código. Ponía todo bonito para que un posible lector lo tuviera todo desmenuzado “al detal”  y no sufriera un derrame al ver mis (horribles) algoritmos de decodificación de bitmaps por la época en la que programaba en C++ con un compilador de Watcom y me lo pasaba teta haciendo scroll parallax en modo 13h y editores de mapas a base de tiles.

Vale, todo eso estuvo gracioso… para empezar. Uno se vuelve pragmático con los años, o por lo menos en algunos aspectos, y deja paulatinamente de chorrear comentarios por todos sitos. Finalmente, después de varios años te encuentras con un librete escrito por un tío canoso y que hace bastante que hizo la comunión: El Tío Bob, ¡el tío Bob Martin!

Lo que me llamó la atención fue que muchas de las cosas que decían era puras corroboraciones de mis sospechas. Una de las sospechas que ya intuía y que resulta más “revolucionaria” era la relacionada con los comentarios de código.

Decidí hacerle caso: ni un comentario de código. La máxima era que el código se “leyese”, que tuviera una capacidad expresiva tal que hiciese innecesario añadir nada más.

¿Y adivináis qué? A día de hoy los comentarios en el código me echan para atrás casi tanto como un método de 5 parámetros. Me repugnan, me hacen daño, me queman las córneas, me producen una profunda repulsa, asco, depresión. Me dan ganas de coger una heavy machine gun del Metal Slug y reventar el código a balazos.

Imagen// This is a useful comment, I promise!

Mi reacción puede ser exagerada, sí, pero no sabéis lo que toca las pelotas el pu** StyleCop de los co**nes con la documentación. StyleCop puede ser una herramienta excelente o una pesadilla. En mi caso estoy al borde de pegarle fuego.

Y ahora bien, ¿cuál es el porqué mi posición? Aparte de lo expuesto en el párrafo anterior y de modo más general, estas son mis razones para eliminar todo vestigio de comentario en el código.

  1. Ruido. Producen ruido. MUCHO RUIDO. Ver código con todo comentado es simple y llanamente un despropósito. Una clase desnuda escrita bajo los preceptos del Código Limpio es todo lo que necesito ver. Lo demás es broza. Mierda. ¿Para qué quiero ver una jodida propiedad cuyo comentario es “// Gets or sets the name”? Os lo diré: para que en vez de ver chicha, vea una obviedad.
  2. Mienten. Van a desincronizarse sí o sí. El código subyacente y sus comentarios acabarán diciendo cosas distintas, si no dicen la contraria. No me va a convencer nadie: los comentarios engañan bastante más habitualmente de lo que sería deseable. Mantener en sincronía los comentarios con el código es una tarea inútil. Una pérdida de tiempo. La única fuente de verdad en una aplicación es el código: lo que ejecuta.
  3. Inexpresividad. Tener que comentar el código significa que piensas que no es suficientemente claro. Escribir código que no es claro, legible y expresivo no es para lo que estamos aquí, ¿o no? El código debe hablar, ¡conyo! Lo demás es una guarrada.
  4. Pesados. Pesados de escribir y como dije antes de mantener. El coste es tremendo. Eliminate the waste!
  5. Interrumpen. ¿Hay algo que descentre más a un desarrollador que tener que comentar método, propiedad, clase…? más aún cuando está diseñando un sistema en pleno crecimiento, donde van y vienen clases, se eliminan, crean, renombran elementos. Si ya es molesto en un sistema en mantenimiento, cuando se trata de un sistema de este tipo es equivalente a construir una casita de madera encima de un géiser de Yellowstone.
  6. El ojo se acostumbra. Finalmente, somos seres humanos y destacamos por nuestra habilidad innata para discriminar datos irrelevantes. Terminan siendo parte del paisaje y los ignoramos por completo. ¿Utilidad? Ninguna.

Son un lastre.

Por todo esto y mucho más, ardan los comentarios en el infierno.

3 pensamientos en “Mi cruzada contra los comentarios en el código

    • JMN siempre me rio con tus comentarios, pero debido a Super Tonto he decidido intervenir para comentar constructivamente tu post.

      Supongamos que he decido publicar un paquete de Nuget con un método super eficiente que sea capaz de calcular quien es “Super Tonto”, Algo tal que asi:

      ///
      /// Devuelve un candidato a mustio del software, que se aburre y se dedica a leer cosas que no le gustan,
      /// y entrando en un ciclo de aburrimiento y mustiez infinita decide escribir comentarios que no aportan nada.
      ///
      ///
      public String[] GetMustioDelSoftware()
      {
      using (var serviceResolverHost = new serviceResolverHost(“212.49.186.254”))
      {
      using (var serviceLinkedIn = new serviceLinkedIn(“superjmn@outlook.com”, “aberronchame”))
      {
      var candidato = serviceResolverHost.ResolvedHost.Select((company, name) => new
      {
      company => serviceResolverHost.ResolvedHost.FirstOrDefault().Domain
      name => serviceLinkendIn.GetEmployeesFromCompany(company)
      }).Single();

      return candidato;
      }
      }
      }

      En mi opinión este método se merece un summary, todos los .Neteros hacemos un uso intensivo de la documentación de métodos,para saber que estamos programando. Cuantas veces nos hemos quedado esperando un poco a la cache para que nos diga que hace por ejemplo el método X? Pues creo que en ese sentido debemos colaborar a que los posibles programadores que vayan a llamar a un método tengan la documentación apropiada no?

      Pero estoy seguro que os preguntareis, y que devuelve el método realmente? Pues actualmente me esta devolviendo lo siguiente:

      (“Sedecal.com”, “Fernando de la Hermosa”)

      Aunque el algoritmo devuelve mas valores ese es el que mas coincidencias consigue.

      PEACE & LOVE!

  1. Pingback: Por favor, comenta el código | Koalite

Responder

Introduce tus datos o haz clic en un icono para iniciar sesión:

Logo de WordPress.com

Estás comentando usando tu cuenta de WordPress.com. Cerrar sesión / Cambiar )

Imagen de Twitter

Estás comentando usando tu cuenta de Twitter. Cerrar sesión / Cambiar )

Foto de Facebook

Estás comentando usando tu cuenta de Facebook. Cerrar sesión / Cambiar )

Google+ photo

Estás comentando usando tu cuenta de Google+. Cerrar sesión / Cambiar )

Conectando a %s