Blog

16
MAY
2017

Código Limpio 01 / Nomenclatura

banner_blog_01

A lo largo de un proyecto, podemos leer 100 líneas de código por cada una que escribamos y eso se cumple más cuanto más grande es el proyecto. Por eso en Dowhile dedicamos buena parte de nuestro esfuerzo en hacer que el código sea lo más fácil de entender posible.

Me gusta definir la programación como un método de comunicación. En este caso, el emisor es el programador y el receptor, la máquina. El diálogo se hará mucho más fácil cuanto más clara tenga la idea que quiera transmitir el programador. Sin embargo no debemos olvidar que ese código probablemente lo tengan que leer nuestros compañeros de trabajo, así que en realidad estamos comunicándonos no solo con la máquina si no potencialmente también con todo el departamento de desarrollo.

Cuando escribimos, en un sentido más tradicional, nos enseñan a releer y reescribir nuestro trabajo. No todos los programadores pueden permitirse hacer lo mismo, aunque comprender 100 líneas de código suele ser más complicado que leer y entender 10 páginas de una novela; con remarcadas excepciones que no voy a citar para evitar irme más por las ramas de lo que ya me he ido.

El “ya funciona” es un cáncer en la buena salud del trabajo en equipo, donde las prisas y las fechas de entrega ajustadas son su principal causante. Releer el código y corregirlo es algo que deberíamos hacer antes de cerrar cualquier tarea.

Dicho eso, podemos decir “pues es verdad, voy a escribir código fácilmente entendible a partir de ahora” pero eso no depende puramente de nosotros; nuestra ignorancia puede matar a nuestras buenas intenciones. El buen código es aquel que es fácil de entender por otras personas además de nosotros, y por eso, gente más sabia que yo ha ido dejando esquemas, consejos o “normas” si lo preferís, para mantener nuestro código limpio y entendible. Hoy empezaremos por la nomenclatura, cómo nombrar variables y funciones en nuestro trabajo. A lo largo de un proyecto pondremos nombre a muchos elementos distintos: variables, funciones, clases, métodos... Por lo que parece una buena idea empezar por aquí.

new-guys-study-code

Guías básicas

Éste es  un recopilatorio de guías que he encontrado, explicadas lo mejor que he sabido, para poder bautizar elementos en el código de la forma más comprensible posible y que aporte el mayor valor al lector humano que venga después de nosotros:

El nombre de una variable debe revelar su cometido. Si necesitas un comentario para aclarar para qué se usa esa variable, le has puesto mal el nombre y deberías volver a pensarlo. Es mucho mejor escribir variables largas que tener que volver más tarde a deducir qué hacía una función porque las variables son $x, $i, $j y $c o parecidos. Además, estos ejemplos serían difíciles de encontrar al hacer una búsqueda en el código, pues muchas otras variables pueden coincidir o contener el texto a buscar.

También hay que evitar confusión entre variables. Sobretodo si éstas tienen funcionalidades completamente distintas. Mientras que si ambas sirven a un propósito similar, es aconsejable que empiecen parecido, como sería $screenWidth o $screenHeight.

Del mismo modo, cuando simplemente añades un número a una nueva variable para diferenciarla de otra que ya existía, eso no aporta ningún tipo de información adicional de las intenciones del desarrollador al crear la variable; hay que evitarlo. Tampoco debemos usar palabras inútiles que no añadan valor al elemento a nombrar. Por ejemplo, no podemos encontrar la diferencia entre $post y $postData sin ver su contexto. Cuando nombras un elemento siempre debes ser capaz de identificarlo sin ver su contexto. Por eso palabras como Data o Info no aportan valor real al nombre y no tiene sentido utilizarlas al nombrar.

Para facilitar la comunicación entre compañeros, cuando tienes que explicar o comentar el código con alguien, es importante utilizar nombres de variables que podamos pronunciar; evita acentos, la letra 'ñ' u otros caracteres especiales impropios de la codificación ASCII al crear las variables, para evitar confusiones y dolores de cabeza innecesarios.

Los prefijos en los nombres de las variables son un arma de doble filo. Por ejemplo, $firstName, $lastName, $street, $ciy y $state se les pueden añadir el prefijo addr para facilitar su comprensión; algunos conceptos pueden significar distintas cosas en distintos entornos, como state. Pero un prefijo demasiado general, como dw o las siglas de un proyecto solo conseguiremos perder funcionalidad de la herramienta de autocompletar de nuestro IDE y, ¿para qué vamos a hacer nuestro trabajo más tedioso de lo que ya es?

En resumen, podemos separar las guías en aspectos a perseguir y aspectos a evitar.

Aspectos a seguir:

✔ Revelar cometido con el nombre de la variable e intención con el nombre de la función
✔ Similitud entre elementos que tengan el mismo objetivo
✔ Nombres pronunciables
✔ Prefijos que aúnen elementos con un mismo objetivo


Aspectos que debemos evitar:

✗ Posibles confusiones entre elementos similares
✗ Palabras que no añaden valor al nombre
✗ Caracteres especiales como la ñ o los acentos
✗ Prefijos repetidos para distintos objetivos o intenciones y que se inmiscuyen en las
herramientas que nos proporciona el IDE (buscador o autocompletar)
 

La mayoría de referencias las podemos encontrar en las siguientes fuentes:

Una ponencia de hace 17 de Junio de 2010 de Robert C. Martin.
El libro “Clean Code” del propio Robert C. Martin.
Un artículo en formaciononline.eu de Buenas prácticas para programar PHP
Wikipedia, Convención de nombres (Programación).
En Seas, Naming Conventions en PHP 5.

Entrada by Agustí Montes.
TAGS FORMACIÓN - PHP - JAVASCRIPT - DESARROLLO WEB

NOTICIAS RELACIONADAS

19/11/2015
by Agustí Montes
22/12/2016
by Hugo
06/10/2015
by Hugo