Código que se documenta solo

¿Cómo escribir código que otros desarrolladores puedan leer?

"Código que se documenta solo" es otra forma de decir "código legible" y "legible" significa que no te volverás loco tratando de entenderlo. No te engañes, no es un reemplazo de la documentación o comentarios bien ubicados, pero nadie resulta dañado al escribir código legible. A continuación describiré algunas ideas que harán que tu código sea más fácil de entender.

No uses números mágicos

Los programadores experimentados ya sabrán a que me refiero. En vez de hacer esto:

if (estudiante.edad > 23) {

¿Qué es 23? Nadie sabe a menos que alguien te lo diga.

Pero si ves esto:

const edadMaxima = 23;
if (estudiante.edad > edadMaxima) {

Se entiende mejor, ¿verdad?

Utiliza nombres claros para las variables

Esto es más fácil de explicar creo, porque lo siguiente:

int g;
int d;
int r;
r = g * d;

Es más difícil de entender que:

int costo;
int cantidad;
int total;
total = costo * cantidad;

Recuerda: un par de semanas después de escribir código como el primer bloque, sólo tu yo del pasado sabrá que significa "g" o "d".

Funciones pequeñas y refactorizar

Bautizar a las variables de forma que se entienda para que fueron creadas, aplica también para las funciones. Aparte de eso, las funciones deben ser lo más pequeñas posibles, aplica en la medida de lo posible la regla de que una función debe efectuar una única acción. No escribas funciones que calculen, impriman, y envíen facturas a la vez. Cada función debe tener su responsabilidad.

Usar funciones y refactorizar ayuda a organizar tus pensamientos mientras programas.

Borrar código comentado

Comentar código es algo que hacemos durante el día, por uno que otro motivo, sin embargo, mantener código comentado por semanas (o meses), sabiendo que ya no va a ser utilizado afecta la legibilidad del código. ¿El código comentado es una especie de control de versiones? Me parece que no es una buena práctica.

Conclusión

• Escribir código legible que se documenta solo, es bueno, pero no nos exime de una buena documentación y de buenos comentarios ubicados correctamente.


• Recuerda constantemente que debes escribir código que pueda ser leído, no para incrementar el número de líneas de código.


• Actúa como una buena persona: cuando pases por el mundo, deja un mejor lugar, cuando escribas código deja algo que le haga la vida más fácil al siguiente programador. Podrías ser tú.