7. Comentarios

Según Steve McConnell, autor de Code Complete: "Un buen código es la mejor documentación". Lamentablemente pocos desarrolladores saben hacer buen código o han sido bendecidos con la capacidad de trasladar su lógica a una estructura que sea fácil de continuar. De ahí que sea necesario dar todas las pistas posibles, explicaciones oportunas con todo el lujo de detalles que sea sanamente posible de elaborar. Ayudarás a tu yo del futuro y posibles herederos.

Para crear un comentario usa un punto y coma al principio de la línea.

;

A diferencia de Lisp donde es obligatorio 2 puntos y comas: ;;.

El contenido del comentario debe ir colocado a su derecha.

; Soy un comentario

Clojure ignorará todo lo que exista en la línea hasta su final.

; (inc 5) Incrementa a 6. <- Este código nunca llegará a ejecutarse.

Es posible añadir más ; con el objetivo de dar un grado de importancia, pero el lenguaje continúa interpretándolo como un simple comentario.

;;;; Tiempo actual en milisegundos
(System/currentTimeMillis)

Estilos

Una buena práctica, para ser consistente con otros programadores, es usar un estilo común a la hora de comentar. Dependiendo de la cantidad de ; podemos dar mayor o menor importancia a los comentarios. La comunidad [^7] ha establecido la siguiente jerarquía.

;;;; Comentario de cabecera o sección

;;; Comentario principal

;; Comentario sencillo o para describir una función

; Comentario para el final de línea

A continuación puedes leer un fragmento de código que hace uso de los estilos en su correcto orden.

;;;; Gestión de la base de datos

;;; Variables

;; Conexión con la base de datos
(def db
  {:classname   "org.sqlite.JDBC"
   :subprotocol "sqlite"
   :subname     "biblioteca.sqlite"
   })

;;; Funciones

(defn insertar-autor
  ;; Inserta un autor a partir de su nombre
  [nombre nacimiento]
  (j/insert! db :autores {:nombre nombre :nacimiento nacimiento}))

(insertar-autor "Miguel de Cervantes" 1547) ; Añade al autor del Quijote

Bloquear código

En Clojure podemos encontrarnos una clara diferenciación entre 2 tipos de comentarios: explicaciones, como acabamos de ver, y bloqueo de código.

Una técnica muy ingrata que todos hacemos cuando necesitamos desactivar fragmentos de código es comentarlo. En cada línea añadimos el respectivo comentario o, en caso contrario, creamos un bloque. Clojure es consciente de ello, por lo que nos proporciona una herramienta para hacernos felices: usar #_.

Partamos del siguiente ejemplo. Quiero cambiar el tipo de 4.2 a un entero (4), y sumarle 5 y 3.

(+ 5 (int 4.2) 3)
; 12

Si quisiera, temporalmente, quitar el argumento que cambia el tipo, tan solo debo añadir delante #_.

(+ 5 #_(int 4.2) 3)
; 8

Lo existente en el paréntesis deja de existir a la hora de ejecutarse, y todo ello sin alterar el funcionamiento de la aplicación.

A la hora de ejecutarlo será interpretado como si no estuviera ahí. Similar a:

(+ 5 3)
; 8

Por muchos elementos que existan dentro del paréntesis.

(+ 1 (reduce * (conj (sorted-set) 3 8 1)) 1)
; 26
(+ 1 #_(reduce * (conj (sorted-set) 3 8 1)) 1)
; 2

Te aseguro que en cuanto lo uses a diario, cuando debas cambiar de lenguaje, lo echarás mucho de menos. Es tan simple como productivo, una idea brillante.

Comentario rico

Su propio nombre es un juego de palabras. El nombre original es Rich Comment, ya que proporciona bloques de código más ricos en el desarrollo al permitir varias líneas de texto con ejemplos. Como anécdota te puedo contar que su nombre viene de quien lo escribió por primera vez, una persona llamada Rich.

Su mecanismo es básico, todo lo que exista dentro de…

(comment
...
)

será completamente ignorado. Independientemente de si alberga un texto o código. Podría ser similar a otros lenguajes que lo denominan como un "comentario de bloque".

(comment

(defn truco []
  ("Tadam!"))

)

Sin embargo debemos ser cuidadosos ya que es leído por el intérprete de Clojure afectando al rendimiento de la aplicación y su validador de sintaxis. En otras palabras, si te olvidas de un paréntesis te mostrará un error a pesar de ser un comentario. La alternativa para que sea completamente ignorado es añadir ; en cada línea o envolverlo entre comillas dobles.

(comment "

(defn truco []
  ('Tadam!'))

Función para realizar trucos de magia!
")

Puedes profundizar en la charla Running With Scissors: Live Coding With Data por Stuart Halloway [^8].

Resumen

• Se comenta usando ; al principio de la línea.

• Existe un estándar de estilos por parte de la comunidad para dar más o menos importancia a cada comentario.

• Con (comment …) podemos crear bloques de comentarios.

Ejercicios

1. ¿Qué devuelve (comment "Space Oddity") en el REPL? ¿Por qué?

2. Intenta crear un comentario rico con varias líneas pulsando Enter al final de la línea. Cierra con un paréntesis.