Probablemente seas nuevo en el mundo de la programación y estés leyendo un libro, tutorial o guía sobre programación; desde ese momento, ¿qué es lo que haces? Estás leyendo en vez de estar escribiendo. Por lo tanto, es muy importante que el nombramiento de las cosas que otros programadores y tú escriban, estén bien escritas.

Y cuando digo “cosas“, me refiero a tus variables, funciones, parámetros e incluso comentarios. Éstos deben ser legibles y dar a entender lo que está haciendo la variable o función, si no lo son, perderás mucho tiempo leyendo el código.

El problema del mal nombramiento de las cosas

Si el nombramiento de las cosas no son legibles y mucho menos entendibles, te podrás ver afectado a futuro. A continuación, te muestro los puntos que probablemente enfrentarás si no nombras bien las cosas.

Tu código no:

• Será legible.
• Podrá ser entendido ni por ti, ni por otros programadores.
• Será escalable; es decir, se te dificultará agregar y/o actualizar el código.

Y la peor de todas, tal vez te tengas que ver obligado a cambiar todo el código.

Escribe tu código en inglés

¿Inglés? ¡Estás loco Roel, no me llevo con eso!

No estoy loco, solo que mayormente la documentación de las librerías y frameworks están escritas en inglés; pocas veces se encuentra en español.

Además, nunca sabes quién leerá tu código.

Por ejemplo: Estás en una empresa escribiendo tu código en español, pero el administrador del proyecto te dice que necesita que le envíes tu código a su amigo americano. ¡Huy, problemas!

Le comentas la situación al administrador del proyecto, y lamentablemente te dice que escribas tu código en inglés. ¡Tristeza! Tienes que volver a escribir el código.

¿Ya ves? Tu código lo podría leer alguien en la India, Estados Unidos, Dinamarca, etc.

No programes para ti, programa para los demás

Te pongo un ejemplo; tu has escrito el siguiente código:

<?php
 
$stuff = array( 'lemon', 'apple', 'pineapple' );
$x     = 'apple';
 
echo $stuff[ $x ];

Y lo tienes que enviar al administrador del proyecto para que revise tu código, él va leyendo las variables y se encuentra con la variable:

$stuff, la cual contiene una colección de frutas. Bueno, su primer pregunta es, ¿por qué la variable $stuff no se llama $fruits? No concuerda con su contenido.

Después se encuentra con la variable $x, la cual es igual a apple. ¿Es enserio? —Se pregunta. Él pensó que la variable $x contenía el valor de una coordenada en el eje X.

Vamos a nombrar bien estas variables:

<?php
 
$fruits   = array( 'lemon', 'apple', 'pineapple' );
$my_fruit = 'apple';
 
echo $fruits[ $my_fruit ];

¿Ves que ahora es más fácil de entender a qué se refiere cada variable? Pero el chiste no es escribir de nuevo el código, eso solo te ha quitado tu valioso tiempo.

Tal vez estos ejemplos sean algo simples y muy ilógicos, pero creanme, me he encontrado con estos casos, y ustedes también lo harán y se frustrarán.

Tus palabras deben ser claras, no uses abreviaciones

Para que lo anterior funcione, debes evitar escribir abreviaciones y las palabras de las acciones de tus variables y métodos deben ser claras, legibles y entendibles.

Por ejemplo, tenemos el siguiente código:

<?php
 
$cat = get_cat_info_by_name( 'products' );
 
echo $cat;

¿A qué nos referimos con el código anterior? ¿Estamos hablando sobre obtener la información de una categoría, de un catálogo o de un gato (cat, en inglés)?

Lo anterior produce confusión y frustración. ¿Qué estás pidiendo en realidad?

Lo correcto sería:

<?php
 
$category = get_category_info_by_name( 'products' );
 
echo $category;

Ahora si que, si tu variable contiene autos, tu variable debe llamarse $cars. Si tu variable contiene tipos de coches, entonces debes llamar a tu variable: $cars_types.

¿Entiendes mi punto?

Pero, tampoco te excedas en nombrar las cosas; es decir, trata de usar palabras cortas, siempre que puedas. Ejemplo:

<?php
 
$categories_filtered_by_created_date = get_categories_by_date('product');
 
var_dump( $categories_filtered_by_created_date );

Hemos usado una variable con una buena cantidad de caracteres; para ser sinceros, se hace un poco difícil de leer. La solución es usar alguna palabra corta:

<?php
 
$categories_by_date = get_categories_by_date('product');
 
var_dump( $categories_by_date );

¿Ves que ahora la variable se lee claramente?

El nombramiento de las funciones y la documentación

La documentación es odiada por todos, yo la odio, pero es buena práctica escribirla, obviamente, clara y simple de entender, como lo hemos visto anteriormente.

¿Por qué? Tú puedes escribir tu código bien escrito, siguiendo las recomendaciones anteriores, pero, ¿qué pasa si quieres leer el código un año después que lo escribiste?

¡Así es! Probablemente no comprendas de qué se trate el código que escribiste, sin embargo, hay algunos casos en los que la documentación no es tan necesaria.

Una documentación puede ser opcional siempre y cuando tu código explique por si solo lo que está haciendo; por ejemplo, y es aquí donde aplicamos el buen nombramiento de las funciones:

Tenemos la función is_plugin_active() de WordPress, la cual sí tiene su propia documentación:

Pero podría ser opcional, ya que el mismo nombre de la función explica lo que está haciendo.

Sin embargo, está la función get_plugin_data(), cuya documentación abarca muchas líneas de código:

¿Notas la gran diferencia? Mientras más hagas entendibles tus códigos, menos documentación tendrás que escribir.

Conclusión

La buena práctica de nombrar bien las cosas es algo muy importante que debes tomar en cuenta, te ayuda a ti mismo y ayuda a demás programadores a ser mejores programadores.

Si mezclas esta buena práctica junto con el mejor manejo de tus condicionales, tu código será elegante y profesional.

Espero que te lleves algo bueno de este post, y apliques los conocimientos en los códigos que hayas hecho o estés por hacer.

Si tienes alguna duda, comentario ó sientes que me faltó algo, por favor, házmelo saber en los comentarios.