Evitando los comentarios

En una aplicación ideal (quien haya visto una que me lo diga, será mi nuevo héroe) entre otras cosas no debería haber sido escrito ni un solo comentario, ya que el propio hecho de usarlos es sinónimo (¿consecuencia tal vez?) de código no legible. Algunos programadores tienden a comentar de forma natural (a veces compulsiva) gran parte de código que escriben, pero con todo el respecto hacia su trabajo la realidad es esa. Por otro lado, el propio comentario cuya supuesta misión es aclarar el código está añadiendo información (y por tanto complejidad) al documento, lo que va a provocar que su objetivo se vea, en mayor o menor medida, defenestrado.

Existen ciertas situaciones puntuales en las que, sin embargo, un comentario puede llegar a ser útil e incluso necesario:

  • Cuando los requerimientos del cliente no han sido definidos con claridad o están pendientes de análisis; también aquellos que son ajenos al ámbito del problema de negocio pero deben ser aplicados
  • Cuando es necesario realizar tratamiento de datos de forma no estándar (por ejemplo al realizar operaciones aritméticas complejas u operaciones extravagantes con cadenas de texto, cuando debemos aplicar una serie de operaciones de forma consecutiva entre las cuales y bajo ciertas condiciones algunas pueden ser opcionales, etc)
  • Cuando necesitamos expresar información relativa al desarrollo y no al problema de negocio (por ejemplo marcar tareas pendientes de realizar, informar de errores que han sido detectados pero aún no corregidos, registrar el origen de un fragmento de código que estamos reusando, etc)
  • Cuando no estamos codificando información si no comunicando información (por ejemplo al hacer referencia a un fragmento de código en un correo electrónico o en un reporte de error, cuando estamos formando personal y necesitamos aclarar conceptos que pueden resultar confusos, etc)

Tal vez los motivos citados para usar comentarios te resulten contundentes (para mí lo son) y por ello estés pensando que un mejor nombre para este artículo hubiera sido algo parecido a Usando buenos comentarios (para mí no lo es): el uso de comentarios debe reducirse a situaciones excepcionales (las cuales suelen ser marginales), su omisión te va a ayudar a escribir mejor código (ya que estarás obligado a que éste refleje una intención per se para poder ser entendido y mantenido), y su abuso te va a inducir a todo lo contrario. Por todo esto, y en caso de duda, es preferible la omisión de unos pocos comentarios útiles a la proliferación de multitud de comentarios inútiles.

Finalmente, los comentarios para la generación de Javadoc's no son omisibles (si buscabas una excusa para no escribirlos, hoy no es tu día de suerte), y no sólo es importante su uso si no también su adecuado mantenimiento.