Muy buenas,
Los comentarios son una parte muy importante a la hora de escribir código, no solo en Java, la verdad es que no importa el lenguaje que estés usando. De la mismo forma, es uno de los recursos que se abusa más. Tanto escribir pocos comentarios como muchos es malo, y ha sido remarcado por algunas celebridades como el autor del libro Clean code (Código limpio), Robert C. Martin. En este libro, el cual tengo pendiente de terminar en estos momentos, hay un capítulo completo dedicado a cómo escribir comentarios, y detalla los pros y contras de estos.

Pero antes de seguir con estos consejos y reglas, vamos a ver cual es el proposito de los comentarios en el código, ¿por qué necesitamos los comentarios? ¿acaso escribir el código no es suficiente? Algunos programadores incluso llegan a decir que a ellos se les paga por escribir código y no comentarios.

En cualquier caso, todos podemos estar de acuerdo en que la mayor parte del tiempo empleado en el desarrollo de un Software se dedica al mantenimiento, y únicamente una pequeña parte se dedica al desarrollo en si. Es en la parte en la que más tiempo se pasa, en el mantenimiento, donde serán necesarios los comentarios.

La mayoría de los programadores no está durante todo el tiempo de vida de un producto Software trabajando en él, y a veces hay gente nueva, la cual debe trabajar con código ya escrito. Esas personas que leen el código y no se interesan por la razón porla cual cierta línea de código está ahí, son a las que les pueden ser útil los comentarios para entender rápido el código.

Vamos a dejar ya las historias y comencemos con una serie de buenas prácticas que todos deberíamos seguir a la hora de escribir comentarios en el código:

  1. Centrate en la legibilidad del código, asume que no existen los comentarios para poder explicar el código. Dales a los métodos, variables y clases nombres con significado.

  2. No escribas lo que hace el código. Esta tarea debería ser relegada al código, y debería ser resuelta de manera sencilla siguiente el consejo anterior.

  3. Escribe siempre porqué estás escribiendo ese trozo de código. La razón de escribir ese trozo de código no es visible hasta que lo escribes en los comentarios, y puede llegar a ser crítico para identificar cualquier bug o comportamiento extraño.

  4. Si estás escribiendo librerías “core”, es decir, que van a ser usadas por varios proyectos y equipos, sigue siempre el estilo para los comentarios indicados por javadoc. Documenta además todas las suposiciones y precondiciones para usar tu API.

  5. Incluye el id de incidencia y descripciones en los comentarios, especialmente si estás modificando un trozo de código como parte de un mantenimiento. Esto es realmente útil a la hora de comprarar diferentes versiones de un mismo código. Esto te da ideas claras de porqué ese código en particular ha sido añadido y/o modificado y si el problema viene de ese trozo de código o no.

  6. Intenta siempre escribir los comentarios con el mínimo de palabras posibles. A nadie le gusta, ni tiene tiempo, de leer comentarios largos.

  7. No incluyas en los comentarios historias como tu nombre, id de empleado, departamento, etc. toda esa información puede ser obtenida, si fuese necesaria, desde los commits realizados y los partes de incidencias durante la fase de mantenimiento.

  8. Escribe siempre comentarios a la hora de hacer commit en el repositorio y en especial el motivo de las modificaciones realizadas. Incluye si es posible en número de incidencia para poder realizar la consulta con más detalle en caso de ser necesario.

  9. Si quieres que los desarrolladores venideros sigan ciertos estándares o informar sobre ciertos detalles, entonces será mejor que los incluyas al principio de tus clases como comentarios.

  10. Por último, pero no menos importante, intenta pasar código a compañeros para que lo lean como parte de la fase de revisión, y ver cuánto son capaces de entender.

Eso es todo por ahora sobre consejos a la hora de crear comentarios que intento usar siempre. Intentar compartir estos conocimientos, y usar las prácticas que mejor os parezcan para escribir buenos comentarios. Creo que esta es una de las areas en las que los programadores nóveles puedes mejorar más (y los más experimentados también).

Saludos,
Lázarus Surazal.

Entradas relacionadas
Perfil
prLázarus logo info
Carlos J. Peláez Rivas (Lázarus Surazal)
Graduado y Máster en Ingeniería Informática por la Universidad de Málaga. Actualmente trabajando como desarrollador de aplicaciones en Java usando Vaadin.
Apasionado de los videojuegos, la música y alguna que otra tecnología, siempre buscando cosas nuevas que aprender y hacer.
Más sobre mi...
Contacto
Notificaciones