Comentarios - Nombres y código de terceros

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.

Uno de los mayores problemas que encontramos cada día en el código con el que trabajamos es la forma en que nombramos clases, métodos, propiedades, campos, y variables. Al utilizar estos elementos nos vemos necesitados de apuntalar el código con comentarios para de alguna forma hacerlo legible:

//Calcular el perímetro del triángulo
float x = y + w + z;
System.out.println("Valor: " + x);

En el ejemplo anterior, a menos que se lea el comentario, no hay forma de decir qué valores representan las variables y, w, y z. Obviamente, después del comentario queda claro que son las dimensiones de los tres lados de un triángulo.

Eliminar el comentario sin afectar la legibilidad del código puede hacerse de dos formas. La primera es renombrando las variables utilizadas para expresar correctamente su función:

float perimetro = lado1 + lado2 + lado3;
System.out.println("Valor: " + perimetro);

Y la segunda variante es la misma que utilizamos para eliminar un bloque de código: crear un método específico que calcule el perímetro del triángulo:

private float calcularPerimetro() {
    ...
    return y + w + z;
}

float x = calcularPerimetro();
System.out.println("Valor: " + x);

Cualquiera de las versiones anteriores es suficientemente clara, pero mi preferida es cuando aplicamos ambas a la misma vez:

private float calcularPerimetro() {
    ...
    return lado1 + lado2 + lado3;
}

float perimetro = calcularPerimetro();
System.out.println("Valor: " + perimetro);

De esta forma el comentario es 100% innecesario y nuestro código es perfectamente legible.

¿Qué sucede cuando usamos código de terceros?

Cuando utilizamos código de terceros y los elementos no están nombrados de la mejor forma, no podemos simplemente modificar el nombre ya que no tenemos acceso al código fuente en cuestión. Tomemos por ejemplo el siguiente método:

//Crea una nueva perspectiva tri-dimensional 
perspectiva();	

El comentario viene a indicarnos que el método está creando una perspectiva, sin él no hay forma de decir qué está sucediendo trás bastidores. Para resolver el problema simplemente creamos un nuevo método con el nombre correcto y desde él llamamos al método heredado:

private void crearPerspectiva3D() {
    perspectiva();
}	

De este modo el comentario deja de tener sentido, y en todo nuestro código podemos utilizar nuestro nuevo método perfectamente claro en su función.

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.