Comentarios - Condiciones y conclusiones

Este post es uno más de la serie "Comentarios - No, no, y no". El listado completo de artículos de la serie se encuentra relacionado al final del post.

El último de los ejemplos que quiero mostrar en esta serie es sobre los comentarios para explicar condiciones booleanas complejas a simple vista. Muchas veces nos encontramos en la posición donde no hay manera de entender una condición determinada a no ser que adicionemos un comentario:

if (figura.getVector().getZ() > 1) { // Si la figura está visible en el espacio 3D...
    ...
}	

Resulta que en nuestro ejemplo podemos asumir que una figura se encuentra visible si su coordenada Z es mayor que 1. El código anterior no usa el término "visibilidad", así que el comentario a todas luces resulta necesario... a no ser que hagamos pequeños cambios para lograr que todo sea más claro:

private boolean esVisibleLaFigura(Figura figura) {
    return figura.getVector().getZ() > 1;
}

if (esVisibleLaFigura(figura)) { 
    ...
}	

Utilizando la misma técnica que discutimos en Comentarios - Bloques de código, reemplazamos la condición original por una función cuyo nombre deje completamente claro cuál es su objetivo, y acto seguido eliminamos el comentario sin temor a sacrificar legibilidad. En dependencia de cuán compleja sea la condición, podemos crear múltiples funciones relacionando diferentes secciones hasta que el código sea completamente legible.

A modo de conclusión

Documentación vs Comentarios: En mi opinión son dos cosas diferentes y creo que debí dejarlo claro desde el primero de los artículos. Documentación es cuando usamos el tipo de comentarios que es procesado por javadoc, o los comentarios XML que soporta .NET. En resumen, es cuando hablamos del "qué" y no del "cómo". La documentación está destinada a explicarle a un usuario "qué" hace el método que va a utilizar. Los comentarios son los que le indican a un programador "cómo" funciona algo. Documentar el código es completamente necesario. Comentar no lo es.

Tipos especiales de comentarios: Muchos IDE utilizan tipos especiales de comentarios para procesar/señalar diferentes acciones en el código, como pueden ser los //TODO o //FIXME utilizados en Eclipse o Visual Studio .NET. A pesar que podemos entrar en una discusión sobre si realmente este tipo de comentarios es beneficioso o no para el código, eso sería parte de otra conversación. Estos comentarios especiales no están destinados a explicar una sección de código mal escrita, sino que tienen una función completamente diferente, por lo que nada tienen que ver con esta serie de artículos.

But don't take me too seriously; I don't get paid to write in here, neither I have a clue most of the time of what I'm talking about.