Mejorando el naming de nuestro código

$result, $resultado, $request, $fecha, … es cierto, poner nombres a las variables y/o los métodos es una de las cosas más difíciles cuando estamos programando. Llegar a poner un buen nombre, establecer cada cosa en su sitio y crear las abstracciones correctas a la primera es un poco complicado. Y mucho más si estamos refactorizando. No te preocupes, el naming es un proceso, no se consigue a la primera.

Este post recopila una serie de trucos, consejos y de cagadas que cometo a la hora de poner nombre o de cambiar los nombres a partes del código.

Las etapas del naming

Buscando en Internet sobre naming y como mejorarlo, me encontré con esta joya Good naming is a process, not a single step una serie de posts sobre como mejorar el naming del código y en especial del legacy code. En esta serie de post Arlo Belshee (el autor) indica que normalmente el camino a recorrer para encontrar un buen nombre es este:

• Missing
• Nonsense
• Honest
• Honest and Complete
• Does the Right Thing
• Intent
• Domain abstraction

Cambiar el nombre de un trozo de programa es un proceso lento, miro una parte del código, intento entender que está sucediendo, tengo una idea de como renombrar/extraer una parte de la funcionalidad y lo hago. Repito este proceso hasta que los nombres sean consistentes y he llegado a un punto en el que esto estoy contento.

Esto parece fácil, pero cuando estoy delante de legacy code se hace cuesta arriba, por eso intento cambiar los nombre poco a poco, aunque sea un foreach, ya que creo que trabajando el naming se mejora la comprensión del código y con ello se paga parte de la deuda técnica.

Este enfoque puede parecer extraño al principio. Después de todo soy programador, sé leer código complejo y mi trabajo es actualizar/mejorar ese código. Pero también es cierto que donde más tiempo invertimos los programadores es en leer código, incluso más que en escribir código, más que en diseñar, más que en reuniones… Por ello creo que una buena manera de pagar la deuda técnica y mejorar nuestro código es escribiendo buenos nombres y renombrando cada poco. Ya que nos haremos más eficientes porque leer el código nos será más sencillo.

Pasos a seguir

• Mirar: no trato de entenderlo todo al 100%, ya que eso me tomaría mucho tiempo e incluso puede que se me fría el cerebro.
• Idea: no es la mejor, pero al menos es algo, inspecciono la idea.
• Escribir: Escribo ese nombre, veo como queda, utilizo thesaurus.com para los sinónimos
• Chequear: Compruebo como queda y si es consistente con las decisiones que he tomado antes o las que creo que tomaré. Inspecciono el impacto ¿Es fácil de buscar, sabré dentro de 2 semanas que es esto, el equipo está de acuerdo?
• Commit: Hacer un commit, con un mensaje bueno sobre el renaming. Intentar no poner «refactor»

¿Y si no encuentro un buen nombre? Pues no pasa nada, intento no frustrarme y seguir hacia delante. Si aun así necesito poner un nombre a algo llamo a esa variable/método Manolo, Joselito, Amalia, nombres que choquen, para así cuando tenga más conocimiento del problema ir a ellos y poder cambiarlos de manera sencilla.

Un pequeño ejemplo

Imagina que nos encontramos con un método como este en un controlador, o mejor en una vista.

$this->preload();

¿Qué hace este método? Podría leer un XML de un servicio, podría cargar datos de una base de datos, o no se cualquier cosa porque leer ese nombre nos hace tener que ir a la función para ver lo que hace.

Tenemos que caminar hacia la honestidad, poner que es lo que hace aunque no tengamos muy claro del todo todo lo que hace

$this->doSomethingWithDBAndDisplayResult();

Esta honestidad también se puede aplicar a las clases porque tener una clase que sea DataManager, ¿manejar los datos de qué?

Poco a veremos que es lo que hace el método y podremos darle el nombre completo y honesto:

$this->parseXMLAndStoreInMemcacheData();

Ahora podemos empezar a encapsular este método en otros más pequeños y seguir con nuestra refactorización, continuar caminando y mejorando nuestro código.

Esto mismo también lo intento aplicar a los test, tener un test que sea testOk, pues no mola. Tenemos que escribir nombres de test que nos indiquen que hace el test algo así como show_error_when_user_not_logged()

Conclusiones

En definitiva, creo que todo esto del naming, no es más que iterar. Sé que a la primera no voy a acertar pero poco a poco iré llegando a un consenso, a una serie de nombres que me hagan la vida más fácil.