Código limpio: Nombres

En esta entrada vamos a entender y profundizar en la importancia de elegir buenos nombres. Es muy importante que te tomes el tiempo necesario para encontrar un buen nombre, y no debes tener ningún miedo a cambiarlo si es que encuentras otro mejor.

Evita el uso de contracciones

Esta es la primera regla y la más sencilla de todas. Cuando programamos, podemos caer en la tentación de crear pequeñas contracciones, dentro de la api de linux por ejemplo nos encontramos con un montón de ellas como por ejemplo mv, cp, chmod y muchas más.

Cuando escribes una contracción puede que en ese momento a tí te parezca obvia, pero es posible que para otra persona en otro contexto no lo sea tanto, así que no merece la pena ahorrarse unos caracteres a cambio de los problemas que puedas generar en el futuro.

Además esta regla te permitirá no entrar en conflicto con la siguiente que es la consistencia. Si usas una contracción en una variable o método, ¿Por qué no usarlo en todas las demás? ¿En cuáles sí y en cuáles no? Acabas de crear un problema donde no lo había.

Sé consistente

Una de las características que vimos del código limpio es que no es fácil de mejorar. Eso significa que el código es consistente. Si has decidido por ejemplo llamar Lesson a la entidad que representa a un profesor, una asignatura, una colección de alumnos y un momento concreto en el tiempo, no deberías utilizar ningún tipo de sinónimos.

Otro elemento que debes tener en cuenta a la hora de producir nombres consistentes es utilizar siempre los mismos verbos para una determinada tarea. Por ejemplo si has decidido que cuando accedas a un repositorio y recuperes un conjunto de lecciones vas a utilizar el verbo get generando nombres del tipo getByUser(), getByState(), getByDate() deberías evitar usar sinónimos del verbo get, como por ejemplo fetchByUser(), findByState(), retrieveByDate().

Utiliza el contexto

Evita repetir conceptos que ya están claros a través del contexto. Continuando con el ejemplo anterior, si estás escribiendo un método dentro de LessonRepository para buscar lecciones por su estado no necesitas indicar que estás buscando lecciones getLessonsByState. Ya te encuentras dentro de LessonRepository así que todos sus métodos deberían devolver por colecciones de lecciones. Debes evitar repetir "Lessons" en cada nombre, siendo getByState() más adecuado./p>

Deberías evitar usar nombres demasiado largos, así como deberías evitar usar nombres demasiado parecidos. Si te encuentras en una situación en la que estás escribiendo un nombre demasiado largo deberías evaluar si puedes utilizar el contexto para generar un nombre más corto.

Por ejemplo si tienes la clase UniversityLessonState que contiene los estados posibles de una lección de la universidad, podrías generar un nuevo namespace del tipo University\Lesson\State obteniendo un nombre de clase mucho más corto y fácil de leer, pero sin haber perdido ningún tipo de información.

Si necesitas dos palabras para definir el nombre de una clase es probable que necesites crear un nuevo contexto, y si necesitas tres palabras definitivamente deberías crear un contexto nuevo.

Hace lo que dice que hace

Entramos en la parte final de las recomendaciones. Sin embargo estas dos últimas son las más importante de todas. Cuando eliges un nombre lo más importante es ser sincero. El nombre que estás eligiendo tiene que servir para identificar qué es lo que contiene.

En general debemos evitar nombres genéricos como data, info, resume, items. En algunos momentos muy concretos puede que tengan sentido, ¿pero que contienen exactamente?. Quizá el autor no sabía que nombre poner y eligió uno de estos.

Si lo que queríamos crear era por ejemplo un conjunto de lecciones filtradas por algunos criterios, podríamos haber elegído lessons o filteredLessons al menos indica que contiene un conjunto de lecciones.

Debemos también evitar nombres que definan qué es lo que necesita el autor en lugar de que es lo que hace un método o clase. Por ejemplo LessonRepository::getForDashboard. Tenemos claro que el autor necesitaba una colección de lecciones para mostrarlas en el dashboard, pero no tenemos ni idea de que criterios tiene en cuenta. Si el criterio para mostrar las lecciones en el dashboard fuera que pertenecieran a un determinado usuario, que estuvieran en un rango determinado de fechas, como por ejemplo los próximos 15 días, y se encontraran en un determinado estado, podríamos haber elegido LessonRepository::getByUserFromToAndState.

Explica cómo debe usarse

Llegamos al último punto. Una vez que has encontrado el nombre adecuado que cumple todos los anteriores requisitos debes plantearte una última pregunta.

¿Explica mi nombre cómo debe ser utilizado? Veamos un ejemplo supongamos que tenemos una clase que se encarga de realizar cambios sobre las lecciones LessonManager::changeDate, el contexto LessonManager nos indica que la entidad que va a modificar es una Lesson y el nombre nos revela que la va a cambiar de estado.

Por coherencia los argumentos deberían ser Lesson, Date en este orden. Sin embargo podemos ayudar a evitar malentendidos, nombrando correctamente los argumentos. LessonManager::changeDate($lesson, $toDate) no deja lugar a ningún tipo de equivocación.

Conclusiones

Cuando escribimos código limpio debemos tener en cuenta a la persona que lo va a leer, y cuando elegimos nombres debemos elegirlos pensando primero en esa persona en hacerle la vida lo más fácil posible.