Esta entrada es sobre una cosa que es muy importante pero que es totalmente inútil para tu programa, los comentarios en Java. Esta herramienta es algo que usarás (o debieras) para pasar information entre humanos, solamente para ellos, nada para cerebros informáticos.

Los comentarios en Java (y en todos los lenguajes de programación) son un elemento muy crítico pero que están pensados solamente para los ojos de las personas que lean el código fuente en dónde se encuentran. Puedes poner lo  que quieras en los comentarios y no afectarán en absoluto a la compilación ni tampoco a la ejecución de programa, pero realmente son muy importantes.

Cuando estás trabajando como desarrollador, en este caso como desarrollador Java, sabes lo que estás haciendo (bueno, debieras saber que estás haciendo), pero quizás algunos días después se te haya olvidado el porqué has hecho lo que has hecho (y de ahí salen los hijos bastardos). Puede ser que tengas muy buena memoria pero puedo asegurarte que olvidarás un montón de detalles.

Pero no solamente tienes que pensar en el escenario que te acabo de contar, también podría ser que estuvieras leyendo el código fuente de otro desarrollador y no tengas la más mínimo idea de porqué ha hecho algo ni que motivación tenía para hacerlo así.

Por eso son tan importantes los comentarios, y más los comentarios en Java, dado que Java destaca por lo “verboso” que puede llegar a ser. Un comentario en Java solo es una herramienta para transmitir información de un humano a otro humano (o cualquier ente que pueda entender el lenguaje humano). Este comentario no va a ser ejecutado y no afectará en nada al sistema donde se ejecute.

Vale pero, ¿cómo son los comentarios en Java? Básicamente se podría decir que hay dos maneras de poner comentarios en Java:

Por un lado, en bloque, tal como se puede ver en el siguiente ejemplo de código:

/*
 El siguiente comando imprime el mensaje de Hello world
 */
System.out.println("Hello world");

Como puedes ver, puedes poner cualquier cosa entre /* y */

Y por otro lado puedes poner una línea como lo siguiente:

// El siguiente comando imprime el mensaje de Hello world
System.out.println("Hello world");

Aquí tienes que poner // por cada línea de comentario.

Y ya está, ya saber todo lo que se puede saber sobre los comentarios en Java. Puedes ponerlos donde quieras y con el contenido que quieras. Pero normalmente se suelen seguir unas pequeñas convenciones sobre los comentarios en Java. Básicamente cosas como poner en el principio de una clase un comentario contando que hace esa clase; también se suelen poner comentarios antes de cada función (sobre todo públicas) y lo mismo para las variables.

Generalmente en el mundo Jvaa se suele utilizar este tipo de comentarios para documentar todo, y por eso el sistema de documentación que se utiliza, javadoc, está basado en los comentarios de Java. En una futura entrada, hablaré sobre como funciona y como usar la herramienta javadoc para crear la documentación, que tags se pueden utilizar y unas cuantas cosas más sobre ello.

Por último me gustaría comentar una cosa. Poner comentarios es algo muy bueno, es algo que mejorará la experiencia de todo desarrollador al tocar un código que no conoce, pero por favor, no utilices comentarios como lo siguiente:

// Asignar a la variable a el resultado de uno más uno
int a = 1 + 1;

El código debería comentarse a si mismo. Me explico, en el ejemplo anterior puedes ver que realmente no necesitas leer el comentario para saber que hace el código. Utilizar comentarios para explicar porqué estás haciendo algo y utiliza el cómo solo para cuando ese algo que estás haciendo es verdaderamente complicado entenderlo.