El desarrollo es una práctica compartida y por eso es importante dejar instrucciones claras sobre la estructura, construcción y funcionamiento de los códigos. Para que estos procedimientos sean armónicos, el papel de los comentarios en Java es clave.

Descubre qué son los comentarios y por qué es importante que los conozcas tras un Curso de Programación con Java, los tipos y las prácticas más recomendables para escribirlos. También te contamos los errores más comunes y los consejos para actualizar los códigos. ¡Ten la información a mano en este artículo!

¿Qué son los comentarios y por qué son importantes en Java?

Los comentarios en Java son anotaciones textuales que se introducen entre las líneas de código para ofrecer indicaciones y aclaraciones sobre el proyecto. En ningún caso afectan a la ejecución del programa, el compilador y la máquina virtual de Java los pasa por alto, pero están a la vista para que cualquier desarrollador pueda leerlos y tenerlos en cuenta.

¿Cuáles son los propósitos de los comentarios en Java? Pueden servir como recordatorio para el propio desarrollador, facilitar la colaboración entre varios desarrolladores y garantizar que el código sea legible. Además, también sirven para deshabilitar un bloque de código sin eliminarlo del todo.

Tipos de comentarios en Java

Existen varios tipos de anotaciones en Java, dependiendo de la extensión del comentario. Pueden ser de una línea, ocupar un bloque o realizarse en múltiples líneas, lo que se conoce como un JavaDoc. Si no te suena ninguno de estos conceptos, continúa leyendo para descubrirlos.

1. Comentarios de línea

A la hora de escribir el código pueden surgir la necesidad de incluir breves anotaciones para dar indicaciones sencillas. Ocupan menos de una fila, por eso se conocen como comentarios de línea.

Para incluirlas dentro del código, lo primero que hay que hacer es abrir la línea con dos barras (//) y a continuación incluir el comentario. Recuerda que el compilador ignorará el texto y que servirá para aclaraciones internas.

2. Comentarios de bloque

Cuando las indicaciones ocuparán más de una línea de código en Java se conocen como comentarios de bloque. Además de servir para ofrecer unas explicaciones más extensas, pueden emplearse para deshabilitar temporalmente partes del código, por el motivo que sea.

Para iniciar un comentario de bloque, debes abrir la anotación con una barra y asterisco (/*). Una vez introduzcas el texto, podrás cerrar el mensaje con un asterisco y una barra (*/). Al igual que sucede con los comentarios de línea, este contenido no influirá en la ejecución del código.

3. Comentarios JavaDoc

Los comentarios Java no solo sirven para darles indicaciones a otros humanos, también puede darle instrucciones al propio sistema. Aquí es donde entran los comentarios JavaDoc, en los que el desarrollador incluye una serie de etiquetas para generar automáticamente una documentación técnica y legible en HTML a partir del código fuente.

Para introducir un comentario JavaDoc, debes abrir la indicación con una barra y dos asteriscos (/**) y una vez introduzcas el comentario y las etiquetas adecuadas, tendrás que cerrarlo con un asterisco y una barra (*/). Las etiquetas se abren con una arroba (@) y las más populares son @return, @param y/o @exception.

Mejores prácticas para escribir comentarios efectivos

El código Java, por encima de todo, debe ser legible para cualquier profesional que tome el relevo. Por eso es fundamental seguir unas prácticas para que se cumpla este principio y aportar comentarios efectivos. ¡Toma nota de las principales!

• Síntesis y claridad. No te vayas por las ramas, el tiempo es oro y tus comentarios deben comprenderse a golpe de vista.
• Incluir el qué y porqué. Incluye el objetivo y los motivos por los que es necesario aplicar el código.
• Aportar, no repetir. Incluye comentarios Java cuando sean necesarios, encontrarse varias anotaciones repetidas hace más tedioso el trabajo.
• Documentación de interfaces. Aporta comentarios Java para dar indicaciones sobre la respuesta en la interfaz del front end.
• Explicación de fórmulas. Cuando sea necesaria una fórmula matemática que no sea obvia, es interesante que expliques los pasos para resolverla.
• Profesionalidad. Aunque los comentarios en Java no los compile la máquina virtual ni son de dominio público, conviene guardar unos marcos de profesionalidad en las anotaciones. Nunca sabes quién leerá ese insulto velado a tu bestie de oficina y reza porque no sea un cliente.

Errores comunes que evitar al comentar tu código en Java

¿Cuáles son los errores más comunes a la hora de incluir comentarios en Java? Desde no incluir ningún comentario a excederse con la extensión, hasta faltar a la coherencia. Toma nota de las precauciones que debes tomar a la hora de escribir tu código.

• Olvidarte de comentar. Dar por hecho los códigos que salieron de tu cabeza puede ser un error y entorpecer el flujo de trabajo, porque es muy fácil que surjan preguntas si los retoma un tercero.
• Extensiones excesivas. Dejar comentarios muy extensos también entorpece el flujo de trabajo entre desarrolladores, porque complica el encontrar los conceptos clave.
• Incoherencia en los mensajes. Para facilitar la lectura del código es recomendable que sigas unos criterios unificados.
• Comentar código deshabilitado. Es una pérdida de tiempo comentar un código deshabilitado, conviene que compruebes que no sea el caso antes de dejar tus palabras.
• Revelar información confidencial. Es muy mala idea revelar información confidencial en cualquier medio público y entre ellos se encuentran las líneas de código. Nunca sabes quién se las puede encontrar.

Consejos para mantener tus comentarios actualizados

Es fácil que a medida que crezca un proyecto los comentarios en código queden obsoletos. Por eso te vamos a facilitar tres consejos para mantenerlos actualizados y evitar que esto pase.

• Revisa. Seguro que tienes localizados los comentarios que ya no proceden en las líneas de código, revisa el proyecto periódicamente para eliminarlos o matizarlos en la medida de lo posible
• Usa JavaDoc. Echa mano de herramientas de generación de documentación técnica de forma automática como JavaDoc para que la información no quede obsoleta.
• Comunica. Cuando realices un cambio, avisa al resto de interesados en el proyecto para que lo tengan en cuenta y revisen sus propias anotaciones para que no haya información obsoleta.

¡Fórmate en Java y crea tus códigos!

La programación con Java es una de las competencias más solicitadas entre los desarrolladores y tú puedes formarte en la materia con este curso a distancia. ¡Rellena el formulario e infórmate sobre nuestra metodología!