Pautas para desarrollar un código limpio y estandarizado

Pautas para desarrollar un código limpio y estandarizado

A la hora de desarrollar un proyecto, tienes que tener presente una cosa: no vas a ser el único que vea y trabaje con ese código. Puede que ahora sí, pero no en un futuro. Por esa razón, quiero enseñarte algunas pautas para desarrollar un código limpio y estandarizado.

Seguro que te ha pasado alguna vez: un cliente te contrata para que hagas unos cambios en un plugin o un tema que le hicieron a medida hace un tiempo, y cuando abres los archivos de código, te encuentras más de mil líneas de variables, funciones,… cada una de su padre y de su madre. En ese momento, te gustaría tenerlo delante y decirle cuatro cosas, por haber escrito un código tan ilegible. ¿Pero qué ocurre cuando es tu propio código el que te cuesta leer? ¿A quién echas las culpas ahora? Para que ni tú del futuro, ni otros desarrolladores que vean tu código sientan ganas de matarte, vamos a ver algunas pautas para desarrollar código limpio y estandarizado.

Pautas para desarrollar un código limpio y estandarizado

Pero antes de eso, si no estás familiarizado con el concepto, te estarás preguntando:

¿Qué es un estándar?

De forma general, un estándar es un conjunto de normas que fijan una serie de expertos de una materia, para que a la hora de crear algo relacionado con esa materia haya una coherencia. En el caso del desarrollo, se utiliza para establecer unas normas en cuanto a declaración de variables, declaración y utilización de funciones, clases, etc. De esta forma, cuando un desarrollador tenga que manipular el código de otro, no le supondrá un gran problema.

Cada lenguaje de programación tiene sus propios estándares. Por aquí dejo enlaces a algunos de los que he encontrado de lenguajes muy utilizados a día de hoy:

Cuando además, una compañía tiene su propio estándar de un lenguaje, se le llama convención de codificación (coding convention).

Pero, ¿es obligatorio el uso de estándares en el desarrollo?

Obligatorio no. Nadie va a venir con una pistola, te va a apuntar, y te va a decir que tienes que programar así. Lo que sí es muy recomendable y una buena práctica. Tampoco es obligatorio seguir el estándar al pie de la letra. Por ejemplo, si tu estándar dice que para las funciones tienes que poner las llaves de apertura al lado de la declaración de la función, pero tú las pones debajo, no va a pasar nada. Lo realmente importante es que al final, el desarrollador que vea tu código lo entienda y no le ardan los ojos.

Por ejemplo:

Código limpio
echo $hello;
echo $my;
echo $world;

Código sucio
echo $hello;
echo( $my );
echo ($dirty);
printf( '%s', $world);

Las distintas formas de renderizar el valor de una variable en el segundo ejemplo, son correctas. Todas van a funcionar. Sin embargo, la mezcla de estándares, en este caso, puede hacer que el desarrollador que vea este código se sienta incómodo a la hora de trabajar con él.

Desarrollando con código limpio

Ahora que ya sabes lo que es un estándar y has podido echar un vistazo al del lenguaje con el que tú trabajas, vamos a ver algunas pautas para desarrollar un código limpio… y estandarizado. Como yo trabajo con PHP (y algo de JavaScript), los ejemplos que ponga van a ser de ese lenguaje. De todas formas, seguro que consigues extrapolarlo a cualquier lenguaje de programación.

Always in English

Si queremos trabajar con estándares, tenemos que utilizar un idioma estándar. Y no hay un idioma más estandarizado que el inglés. El inglés es un idioma que todos, en mayor o menor medida, entendemos. ¿Qué línea de código entiendes tu mejor?

$fecha_actual = date( 'd/m/Y') o $current_date = date( 'd/m/Y')

Sí. Si eres de habla hispana, lo más probable es que sea la primera. ¿Pero qué ocurre en este otro caso?

$tekushchaya_data = date( 'd/m/Y')

Aquí, a no ser que sepas ruso, cuando veas esa variable a lo largo del código, no sabrás para qué sirve. Lo mismo le ocurrirá a un ruso cuando vea $fecha_actual. Por esta razón, es mejor desarrollar en un idioma que entendamos todos: inglés.

Nombres identificativos

El nombre de una variable o una función debe de ser descriptivo de lo que contiene o hace, por eso es recomendable que inviertas un poco de tiempo en pensar bien cómo la vas a llamar.

Puede que cuando la declares, tengas claro que la variable $a = 'JuanMa' va a almacenar un nombre. Pero, ¿qué ocurrirá, cuando unas cuantas líneas después, veas algo como esto? echo $a ¿Qué valor tenía almacenado? Te va a tocar hacer scroll varias veces para comprobarlo. Sin embargo, si haces algo como esto, $user_name = ‘JuanMa’ te será más fácil identificar para qué sirve.

Lo mismo ocurre con las funciones. No es lo mismo a() que getUserData().

No repitas código

Imagina que tienes un array de instrumentos, y que tienes que renderizarlos todos por pantalla. En este caso, tienes dos opciones para hacerlo:

$instruments = array( 'drum', 'trumpet', 'fiddle', '...', 'saxophone' );
echo $instruments[0] = 'drum';
echo $instruments[1] = 'trumpet';
echo $instruments[2] = 'fiddle';
...
echo $instruments[20] = 'saxophone';

o

$instruments = array( 'drum', 'trumpet', 'fiddle', '...', 'saxophone' );
foreach( $instruments as $instrument ) {
    echo $instrument;
}

En el primer caso has necesitado 22 líneas de código para renderizar todos los instrumentos. En el segundo, solo 4. ¿Cuál crees que es más limpio?

Divide y vencerás

Además, ahora imagina que eso mismo que acabamos de hacer, tuvieses que hacerlo en varios archivos de tu proyecto. Podrías pensar «bueno, es solo un array y un foreach, así que lo puedo ir repitiendo. Pero ya estarías incumpliendo la norma de no repetir código. ¿Qué puedes hacer entonces? Pues tan sencillo como encerrarlo en una función.

function render_instruments()
{
    $instruments = array( 'drum', 'trumpet', 'fiddle', '...', 'saxophone' );
    foreach( $instruments as $instrument ) {
        echo $instrument;
    }
}

Ahora, ya no es que solo con solo una línea de código en cada archivo, renderizarás tu listado de instrumentos. Sino que si quieres añadir un nuevo instrumento al array, o que cada instrumento se renderice en negrita, no tendrás que modificar todos los archivos en los que está ese trozo de código, sino que solo tendrás que modificar la función:

function render_instruments()
{
    $instruments = array( 'drum', 'trumpet', 'fiddle', '...', 'saxophone', 'clarinet' );
    foreach( $instruments as $instrument ) {
        echo '<strong>' . $instrument . '</strong>';
    }
}

Los espacios en blanco son tus amigos

Pues sí, que no te de miedo hacer un salto de línea extra para separar fragmentos de código con distinta utilidad. ¿Qué código lees más fácilmente? ¿Este…?

$user_data = array( 'name' => 'Juan Manuel', 'last_name' => 'Civico Cabrera', 'age' => 31, 'city' => 'Carchuna (GR)' );
echo '<h2>The user data</h2><ul>';
foreach( $user_data as $data ) {
    echo '<li>' . $data . '</li>';
}
echo '</ul>';

¿… o este?

$user_data = array( 
    'name' => 'Juan Manuel',
    'last_name' => 'Civico Cabrera',
    'age' => 31,
    'city' => 'Carchuna (GR)'
);

echo '<h2>The user data</h2>';
echo '<ul>';

foreach( $user_data as $data ) {
    echo '<li>' . $data . '</li>';
}

echo '</ul>';

Es cierto que el número de líneas de código aumenta, pero así lo vas a agradecer a la hora de mantener tu proyecto. Recuerda también tener en cuenta el consejo de los puntos anteriores, y dividir el código en funciones si ves que este se va a utilizar en varios puntos o archivos.

Utiliza los condicionales ternarios… cuando sea conveniente

Por si aún no lo sabes, los condicionales ternarios son una forma de hacer un if…else. La estructura de un condicional ternario es la siguiente:

condition ? true : false

Como puedes ver, es una función que devuelve un valor en caso de que la condición sea verdadera, u otro si es falsa (o nula). Una característica de este tipo de condicional, es que puedes almacenar el valor que devuelve en una variable. De esta forma, podrías hacer lo siguiente:

$user_name = $user_id === 1 ? 'JuanMa' : 'Sonia'

Sin embargo, como he dicho antes, esto solo sustituye al condicional if…else, pero nunca a un if…else if…else. Esto, sería un mal uso del condicional ternario:

$user_name = $user_id === 1 ? 'JuanMa' : ( $user_id === 2 ? 'Sonia' : 'Delia' )

Para eso, lo mejor es utilizar el condicional de siempre:

if ( $user_id === 1 )
    $user_name = 'JuanMa';
else if ( $user_id === 2 )
    $user_name = 'Sonia';
else
    $user_name = 'Delia';

Conclusiones

Como puedes ver, trabajar utilizando estándares y escribiendo código limpio te puede ayudar, tanto a ti, como a otros programadores que vean tus proyectos, a mantenerlos de una forma más fácil. A lo largo de este artículo te he enseñado algunas pautas a seguir para lograr este objetivo, aunque si nos pusiésemos a repasarlos todos, daría para 3 o 4 artículos.

Es por eso, que te animo a que si conoces alguna recomendación que yo no haya puesto aquí, te animo a que la compartas a través de los comentarios. Y por supuesto, si hay algo más en lo que te pueda ayudar, no dudes en escribirme a través de mi formulario de contacto.

También te invito a leer estos dos artículos de Sonia Ruiz, en los que podrás aprender cómo organizar correctamente tu código con Metodologías CSS y 10 buenas prácticas de HTML para escribir código limpio y mantenible.