Introducción a la segunda edición

Hace ya unos cuantos años que escribí Refactor Cotidiano como una especie de guía sobre cuando y qué refactorizar en el trabajo diario como desarrolladora.

Cuando comencé a trabajar profesionalmente en el mundo de la programación, la idea de refactorizar no me resultó nunca extraña. Como persona que llevaba escribiendo blogs y otros textos desde años atrás, y viniendo del mundo educativo, estaba muy habituada a la idea de revisar y refinar todos los textos que escribía. Se convierte en algo natural, tanto para evitar en lo posible faltas de ortografía o sintaxis, como para asegurar que lo escrito refleja correctamente tu pensamiento y puede generar el efecto que pretendes cuando sea leído.

Por esa razón, mi estilo de programación se parece mucho al proceso que seguía y sigo al escribir. Expreso una idea en código y trato de refinarla en sucesivas revisiones, las cuales me permiten entender mejor lo que estoy haciendo y me abren oportunidades para otras mejoras.

A veces, resulta difícil encontrar la forma adecuada de expresar un concepto mediante código. En ese caso, intento hacerlo de forma basta, aunque funcional. Una vez que lo tengo delante, es cuando puedo examinarlo en busca de ciertos patrones que me dan las pistas de cómo modificarlo para que la expresividad y el diseño sean mejores.

Esto tiene un límite. Muchas veces ocurre que mi conocimiento actual del dominio en el que esté trabajando no es suficiente para expresarlo de la mejor manera. Y en esos casos, el código va así a producción: es funcional, hace lo que se supone que debe hacer, pero es manifiestamente mejorable. No pretendo seguir dando más vueltas hasta encontrar la versión perfecta. Esas mejoras llegarán en un futuro, cuando una nueva intervención nos lleve por esos mismos archivos, pero esta vez con un mejor conocimiento.

Acerca de este libro

Refactor cotidiano no es un catálogo de técnicas al estilo del Refactoring de M. Fowler, sino más bien una colección de ideas sobre temas o áreas en las que fijarse cuando estamos trabajando.

Por ejemplo, el libro empieza hablando de los comentarios y discute algunos de los problemas que pueden aparecer relacionados con ellos, cuando usarlos y cómo hacer para que sean innecesarios.

Acerca de la segunda edición

Refactor cotidiano tiene el honor de haber sido el libro de la primera edición de la PulpoCon (2019). Esta conferencia dedicada al desarrollo de software con orientación crafter se celebra en Vigo, en algún fin de semana de septiembre, y ya va por la tercera edición a la hora de escribir estas líneas.

El caso es que la conferencia adoptó la costumbre de regalar un libro exclusivo a las personas asistentes y cuando Rolando Caldas, su organizador, me comentó la idea me di cuenta de que una serie de artículos publicada en el blog podría convertirse fácilmente en ese libro.

Siempre tuve la sensación de que no era ninguna maravilla, pero por lo visto resultó útil a muchas personas, de lo que me alegro. El caso es que poco después de la celebración de la última conferencia me planteé revisar el libro.

Al releerlo me sorprendió que no había envejecido tan mal como pensaba, salvo por los ejemplos de código, que son de PHP y de una versión relativamente antigua. Pero, por otro lado, se me ocurrió que tal vez se podrían ampliar algunos capítulos, retirar las alusiones al blog, mejorar los ejemplos, tal vez introducir otros lenguajes, y convertir el libro en un manual un poco más moderno y más transversal.

Siendo un poco más sistemático, las áreas de mejora del libro:

• En algunos capítulos se remite a la lectora a páginas del blog para ampliar la explicación del porqué de algunos refactors. Esta explicación podría incorporarse en el capítulo para completarlos, aunque sea de forma resumida.
• El capítulo de enumerables es un poco específico de la situación de PHP en el momento de escribirlo. El lenguaje ahora tiene la suya propia, más similar a la de otros lenguajes. Diría que este capítulo necesita una reescritura más profunda que refleje la nueva realidad y que aproveche los puntos positivos de la propuesta original del libro.
• Se echa de menos el tema del refactor a colecciones, lo que merece posiblemente su propio capítulo.
• Otro asunto que tiene más que ver con el enfoque es: ¿por qué no estructurar el libro en torno a problemas frecuentes del código y cómo abordarlos mediante refactor? Algo similar a los code smells, pero quizá expresados de una manera menos taxonómica.
• Revisar el lenguaje y la expresión, aclarando algunos párrafos confusos.

Así que con estas ideas en la cabeza, empecé a trabajar, intercalando con otros proyectos. A medida que iba tomando forma, surgieron algunas ideas:

• Algunos cambios en la organización del índice
• Incluir un capítulo para sugerencias de lecturas y otros recursos
• Una pequeña introducción a cada capítulo, de estilo pretendidamente humorístico
• Notas a la segunda edición en cada capítulo, explicando los cambios introducidos en el capítulo cuando van más allá de la revisión de estilo o expresión.

Introducción de la primera edición

En The Talking Bit hemos escrito bastante sobre refactor, principalmente porque nos parece que es una de las mejores cosas que podemos hacer con nuestro código, sea nuevo o legacy. El refactor es una forma de mantenimiento del código que consiste en mejorar su expresividad a través de pequeños cambios que no alteran el comportamiento y que tampoco cambian sustancialmente la implementación.

Una reescritura, por el contrario, suele plantear un cambio brusco de implementación que podría incluso provocar cambios en el comportamiento. Este proceso busca reconstruir el software a partir de nuevos principios o ideas.

Por otro lado, el refactor puede hacerse de una manera continua e iterativa, interviniendo en el código siempre que se tenga ocasión. Por ejemplo: porque estamos revisándolo a fin de corregir un error o añadir una nueva característica.

Durante el proceso de lectura y análisis podemos encontrarnos con fragmentos de código que no expresan bien un concepto del dominio, que no se entienden fácilmente o que interfieren en la compresión de ese código. Ese momento es ideal para realizar pequeños refactors seguros que, acumulados a lo largo del tiempo, van haciendo que el código evolucione hacia un mejor diseño. Pero sobre todo, hacen que el código refleje cada vez mejor el conocimiento que tenemos.

Como ya hemos mencionado en otras ocasiones, el refactor trata principalmente sobre conocimiento y significado. Es decir, trata sobre que el código exprese cosas y, concretamente, que exprese de la mejor forma posible nuestro conocimiento sobre el dominio en el que trabajamos y cómo estamos resolviendo los problemas que nos plantea.

Por esa razón, se nos ha ocurrido que podría ser buena idea crear una especie de curso o guía para aprender sobre cómo hacer refactor cotidiano.

Refactor sin piedad

El refactor cotidiano es otro nombre para una práctica de Extreme Programming conocida como refactor sin piedad. Dicho en pocas palabras, consiste en refactorizar el código en cualquier momento en que sea posible. Contra lo que podría parecer no se trata de engolfarse dando vueltas al código hasta llegar a un código perfecto, sino de realizar retoques limitados para corregir lo que en ese momento podemos considerar como pequeñas imperfecciones. Por ejemplo:

• Un nombre no consigue expresar correctamente un concepto.
• Una expresión compleja podría descomponerse otras más pequeñas, más fáciles de entender y mantener.
• El cuerpo de un método o función es muy largo y puede ser dividido en secciones autónomas.
• Una expresión condicional es difícil de entender y se puede encapsular como función o método con un nombre expresivo, ocultando sus detalles.
• Una estructura condicional presenta demasiada anidación, de modo que extraemos sus partes para organizarlo según niveles de abstracción.
• Un fragmento de código está en lugar inadecuado y lo movemos a donde corresponde.

Con el tiempo, la acumulación de estos pequeños cambios irá mejorando la estructura, expresividad y mantenibilidad del código. Es muy posible que acabe revelando oportunidades de cambio de mayor calado que tal vez impliquen un rediseño.

En cualquier caso, al mejorar la situación del código, mejoran nuestras posibilidades de intervenir en él. Incorporar nuevas prestaciones será más rápido y seguro, lo que nos permite entregar con mayor frecuencia y predictibilidad.

Los momentos del refactor

En su charla Flows of refactoring, Martin Fowler explica qué es realmente el refactor y cuándo se tendría que hacer.

Fowler insiste en la idea de que si necesitas un momento especial para refactorizar es que no lo estás haciendo, sino, tal vez, reescribiendo o cambiando el diseño de tu software.

Existen tres momentos principales para el refactor:

• Durante la lectura de código
• Refactor preparatorio para introducir un cambio
• Refactor posterior a un cambio

Lectura de código, los momentos WTF

Pasamos la mayor parte del tiempo leyendo código. Cada vez que queremos introducir un cambio necesitamos leer el código existente para saber dónde es el mejor lugar para hacerlo o averiguar qué recursos ya están disponibles. También leemos el código simplemente para buscar algún tipo de conocimiento relacionado con el código mismo o el negocio.

En esos momentos podemos encontrarnos con fragmentos que nos hagan lanzar una interjección (WTF!), o que necesitamos leer dos o tres veces para entender lo que ocurre. Momentos en los que vemos algo que, por alguna razón no cuadra. No es que no funcione, es simplemente que hay algo descolocado, sucio, fuera de sitio, desentonando. En una palabra: desordenado.

Por lo general, estos momentos de extrañeza los genera la existencia de una distancia entre nuestro conocimiento del negocio y cómo se expresa en el propio código. Este desfase es lo que Ward Cunningham denominó deuda técnica.

La deuda técnica se paga refactorizando el software para que refleje el conocimiento del negocio de la mejor manera posible.

En cierto modo, es imposible evitar que el código tenga un cierto nivel de deuda técnica porque el conocimiento del negocio cambia mucho más rápidamente. De hecho, cuando introducimos cambios en el software y los llevamos a producción, el negocio ya está cambiando. En parte, gracias a las nuevas funcionalidades del software y al impacto que tienen.

La forma de prevenir el crecimiento de la deuda técnica es entregar de forma sostenida pequeños cambios y refactorizar constantemente.

Refactor preparatorio

Al introducir cambios en el código para incorporar nuevas funcionalidades o corregir errores suele ser necesario arreglar el código existente para hacer posibles esos mismos cambios. Una cita de Kent Beck lo expresa más o menos así:

For each desired change, make the change easy (warning: this may be hard), then make the easy change

Es decir:

Primero, haz que el cambio sea fácil (advertencia: puede ser difícil conseguirlo). Luego haz el cambio fácil.

Con frecuencia el código no está preparado para admitir ciertos cambios, por lo que debemos transformarlo primero a fin de que la nueva funcionalidad sea fácil de introducir.

Esto es lo que denominamos refactor preparatorio y debería hacerse siempre antes de introducir los nuevos cambios. En otras palabras: mejoramos la estructura del código asegurándonos de no cambiar su comportamiento. Mezclamos esos cambios y solo entonces procedemos a desarrollar la nueva funcionalidad.

Usando otra metáfora de Kent Beck: usamos dos sombreros: el de refactorizar y el de crear nueva funcionalidad. No podemos llevar los dos sombreros a la vez.

Refactor posterior a un cambio

Tras realizar los cambios necesarios volvemos a encasquetarnos el sombrero de refactor para limpiar el código que acabamos de introducir.

Es posible que nuestra nueva funcionalidad haya introducido algo de duplicación y esto podría revelar la existencia de un concepto más general que hasta entonces no habíamos descubierto. En otras ocasiones, el código nuevo incrementa la complejidad de algún área y debemos trabajar para simplificarla.

Al añadir código a un sistema de software, aumentamos su entropía o desorden. La entropía de software es un concepto introducido por Ivar Jacobson y otros en el libro Object-Oriented Software Engineering: A Use Case Driven Approach. La mejor forma de luchar contra un crecimiento desmesurado de la entropía, es aplicar un refactor continuado, particularmente tras introducir código nuevo.

Cómo refactorizar

La idea del refactor cotidiano es muy simple: Se trata de realizar pequeños cambios inocuos en nuestro código en cualquier momento que se nos presente la ocasión. Es lo que algunos autores denominan refactor oportunista. Nuestra propuesta concreta es que hagas un refactor muy pequeño cada vez que lo veas necesario, de modo que, en una primera fase:

• solo tocas un archivo.
• los cambios quedan recogidos en un único commit atómico, que contengan solo los cambios debidos a ese refactor.

En una segunda fase, a medida que ganas confianza:

• los cambios podrían afectar a varios archivos, pero el ámbito es limitado.
• los cambios quedan recogidos en un único commit atómico.

En una tercera fase:

• los cambios podrían suponer introducción de nuevas clases.
• de nuevo, los cambios quedarían recogidos en un único commit.

La guía

Esta guía se compone de una serie de capítulos en los que se exponen diversas orientaciones y principios que seguir a la hora de refactorizar. La idea es explicar ámbitos en los que podrías intervenir en los tres niveles indicados en el apartado anterior. En muchos casos los refactors propuestos, al menos en el primer nivel o fase no necesitarían tests porque podrían ejecutarse mediante herramientas del IDE.

Con el tiempo, es posible que esos pequeños refactors acumulado día tras día, mejoren la forma y calidad de tu código y te despejen caminos para mejorar su expresividad y arquitectura.

Así que, ¡happy tiding!

Capítulo 1. Cuando los comentarios confunden

En el que se trata de como gestionar los comentarios de un código, con especial atención a las situaciones en que el comentario más que ayudar nos confunde, así como criterios para decidir qué comentarios mantener y cuáles no.

Comentarios y documentación

Los lenguajes de programación incluyen la posibilidad de insertar comentarios en el código como forma de añadir documentación al mismo. Es decir: el objetivo de los comentarios es poner conocimiento cerca del lugar en el que puede ser necesario.

Los comentarios en el código parecen una buena idea y, probablemente, eran más útiles en otros tiempos, cuando la necesidad de economizar recursos y las limitaciones de los lenguajes de programación no nos permitían escribir un código lo bastante expresivo como para ser capaz de documentarse a sí mismo.

Así que, en este capítulo, intentaremos explicar qué comentarios nos sobran y por qué, y cuáles dejar.

Notas de la segunda edición

No hay grandes cambios en este capítulo. En general, se mantienen las mismas ideas que en la primera edición. Lo más significativo es que hemos añadido una sección con una heurística (las seis preguntas) que puede ser útil cuando tengas que decidir si añadir o mantener un comentario.

Por lo demás, este capítulo no es una diatriba general contra los comentarios o la documentación en el código, sino contra la documentación innecesaria, desactualizada o aquella que puede quedar fácilmente desactualizada.

Como norma general, la documentación debería estar lo más cerca posible del propio código. Esta podría ser una forma útil de organizar la documentación:

• El código expresa claramente qué hace y cómo.
• Los tests documentan cómo se usa el código, mediante ejemplos que se pueden ejecutar.
• Se añaden comentarios cuando clarifican el porqué de ciertas decisiones.
• El gestor de versiones documenta la historia del desarrollo.
• El archivo README explica la naturaleza del proyecto, su relación con otros proyectos en su caso, y documenta el proceso de instalación, uso en local, desarrollo y testing.
• Mejor aún si estos procesos están automatizados, mediante una herramienta tipo make o la equivalente para un ecosistema específico. Considérala una pipeline local.
• El archivo README enlaza a documentos que puedan ser útiles, como how-to, configuración del IDE para el proyecto, o cualquier otro proceso que se considere oportuno, y se guardan en el mismo repositorio.
• Las decisiones más abstractas sobre el código, como pueden ser decisiones sobre diseño, convenciones de código, decisiones sobre tecnologías, etc., se pueden documentar mediante Architecture Decision Records (ADR), que se guardarán también en el repositorio.
• Los manuales de uso de la aplicación o el software pueden documentarse externamente, pero es conveniente enlazarlo en el README del proyecto, que actuaría como punto de entrada.

¿Por qué deberías eliminar comentarios?

Las principales razones para borrar comentarios son:

Suponen una dificultad añadida para leer el código. En muchos aspectos, los comentarios presentan una narrativa paralela a la del código y nuestro cerebro tiende a enfocarse en una de las dos. Si nos enfocamos en la de los comentarios, no estamos leyendo el código. Si nos enfocamos en la del código: ¿para qué queremos comentarios?

Los comentarios suponen una carga cognitiva. Incluso leyéndolos con el rabillo del ojo, los comentarios pueden suponer una carga cognitiva si, de algún modo, discrepan con lo que el código dice. Esto puede interrumpir tu flujo de lectura hasta que consigues aclarar si ese comentario tiene algún valor o no.

Pueden alargar innecesariamente un bloque de código. Idealmente, deberías poder leer un bloque de código en una sola pantalla. Los comentarios añaden líneas que podrían provocar que tengas que deslizar para ver todo el bloque. Son especialmente problemáticos los que están intercalados con las líneas de código.

Pueden mentir. Con el tiempo, si no se hace mantenimiento de los comentarios, estos acaban siendo mentirosos. Esto ocurre porque los cambios en el código no siempre son reflejados con cambios en los comentarios por lo que llegará un momento en que unos y otros no tengan nada que ver.

Refactor de comentarios

Básico

Simplemente, eliminamos los comentarios que no necesitamos. Es un refactor completamente seguro, ya que no afecta de ningún modo al código.

Reemplazar comentarios por mejores nombres

Eliminamos comentarios obvios, redundantes o innecesarios, cambiando el nombre de los símbolos que tratan de explicar.

Cambiar nombres es un refactor muy seguro, sobre todo con la ayuda de un buen IDE, que puede realizarlo automáticamente, y dentro de ámbitos seguros, como método o variables privadas.

Reemplazar comentarios por nuevas implementaciones

En algunos casos podríamos plantearnos mejorar el diseño de una parte del código porque al reflexionar sobre la necesidad de mantener un comentario nos damos cuenta de que es posible expresar la misma idea en el código.

Este tipo de refactor no encaja en la idea de esta serie sobre refactor cotidiano, pero plantea el modo en que los pequeños refactors del día a día van despejando el camino para refactors e incluso reescrituras de mayor alcance.

Comentarios redundantes

Los comentarios redundantes son aquellos que nos repiten lo que ya dice el código, por lo que podemos eliminarlos.

Por ejemplo:

1 // Class to represent a Book
2 class Book
3 {
4     //...
5 }

En serio, ¿qué nos aporta este comentario que no esté ya expresado?

1 class Book
2 {
3     //...
4 }

Los lenguajes fuertemente tipados, que soportan type hinting y/o return typing, nos ahorran toneladas de comentarios. Y de tests.

 1 class Book
 2 {
 3     /**
 4     * Creates a book with a title and an author
 5     *
 6     * @param Title $title
 7     * @param Author $author
 8     * @returns Book
 9     */
10     public static function create(Title $title, Author $author): Book
11     {
12         //
13     }
14 }

Los tipos de los parámetros y del objeto devuelto están explícitos en el código, por lo que es redundante que aparezcan como comentarios.

 1 class Book
 2 {
 3     /**
 4     * Creates a book with a title and an author
 5     */
 6     public static function create(Title $title, Author $author): Book
 7     {
 8         //
 9     }
10 }

Excepciones: este tipo de comentarios tiene su razón de ser cuando no podemos hacer explícitos los tipos.

Puedes eliminar los comentarios redundantes poniendo mejores nombres. Por ejemplo, en este caso en que utilizamos un constructor secundario:

 1 class Book
 2 {
 3     /**
 4     * Creates a book with a title and an author
 5     */
 6     public static function create(Title $title, Author $author): Book
 7     {
 8         //
 9     }
10 }

Con un nombre expresivo ya no necesitamos comentario:

1 class Book
2 {
3     public static function withTitleAndAuthor(Title $title, Author $aut\
4 hor): Book
5     {
6         //
7     }
8 }

O incluso más explícito:

1 class Book
2 {
3     public static function newWithTitleAndAuthor(Title $title, Author $\
4 author): Book
5     {
6         //
7     }
8 }

Y podemos usar el objeto así, lo cual documenta perfectamente lo que está pasando:

1 $newBook = Book::withTitleAndAuthor($title, $author);

1 $newBook = Book::newWithTitleAndAuthor($title, $author);

Más excepciones: si lo que estamos desarrollando es una librería que pueda utilizarse en múltiples proyectos, incluso que no sean nuestros, los comentarios que describen lo que hace el código pueden ser necesarios.

Comentarios mentirosos

Los comentarios mentirosos son aquellos que dicen algo distinto que el código. Y, por tanto, deben desaparecer.

¿De dónde vienen los comentarios mentirosos? Sencillamente, ha ocurrido que los comentarios se han quedado olvidados, sin mantenimiento, mientras que el código ha evolucionado. Por eso, cuando los lees hoy es posible que digan cosas que ya no valen para nada.

Mi experiencia personal con este tipo de comentarios cuando entro a un código nuevo suele ser bastante negativa. Si el comentario y el código difieren te encuentras con el problema de decidir a cuál de los dos hacer caso. Lo cierto es que el código manda porque es lo que realmente se está ejecutando y lo que está produciendo resultados, pero la existencia del comentario genera esa inquietud: ¿por qué el comentario dice una cosa y el código hace otra?

Habitualmente, debería ser suficiente con comprobar si hay diferencias en la fecha en que se añadió el comentario y la fecha en la que se modificó el código. Si esta es posterior, es que tenemos un caso de comentario mentiroso por abandono y lo más adecuado sería borrarlo.

Este hecho debería bastar para que no añadas nuevos comentarios sin una buena razón. Tendemos a ignorar los comentarios triviales, de modo que cuando cambiamos el código nos despreocupamos de mantenerlos actualizados y acaban siendo mentirosos. Así que procuraremos dejar solo aquellos comentarios que nos importen realmente.

Si ya nos hemos librado de los comentarios redundantes, deberíamos contar solo con los que pueden aportar alguna información útil, así que nos toca examinarlos para asegurarnos de que no sean mentirosos. Y serán mentirosos si no nos cuentan lo mismo que cuenta el código.

Puede parecer un poco absurdo, pero al fin y al cabo los comentarios simplemente están ahí y no les prestamos mucha atención, salvo que sea la primera vez que nos movemos por cierto fragmento de código y tratamos de aprovechar cualquier información que nos parezca útil. Es entonces cuando descubrimos comentarios que pueden oscilar entre lo simplemente desactualizado y lo esperpéntico.

Así que, fuera con ellos. Algunos ejemplos:

To-dos olvidados. Las anotaciones To do seguramente hace meses que han dejado de tener sentido. Mienten en tanto que no tenemos ninguna referencia que les aporte significado.

¿De qué otro tipo de servicio estábamos hablando aquí hace tres meses? ¿Será que ya lo hemos cambiado?

1 // @todo we should use another kind of service here
2 
3 $service = new Service();
4 $service->execute();

Sería diferente si el comentario fuese mucho más preciso y detallado, de tal forma que indique con claridad el ámbito y plazo de la tarea pendiente. Algo así:

1 /**
2 @todo we should replace this service with the new implementation that s\
3 upport Kafka brokers when infra team finished the migration from SQS, s\
4 cheduled for 18/09/2023
5 */
6 
7 $service = new Service();
8 $service->execute();

En ese caso, el comentario hace explícitos unos detalles que definen con precisión los motivos, acciones y plazos.

Comentarios olvidados. En algunos casos puede ocurrir que simplemente nos hayamos dejado comentarios olvidados. Por ejemplo, podríamos haber usado comentarios para definir las líneas básicas de un algoritmo, que es una técnica bien conocida, y ahí se habrían quedado. Todo ello también tiene que desaparecer:

 1 public function calculateFee(Request $dataToCalculate)
 2 {
 3     // Normalize amounts to same currency
 4     
 5     // ... code here
 6     
 7     // Perform initial calculation
 8     
 9     // ... more code here
10     
11     // Apply transormation
12     
13     // .., more code here
14 }

Comentarios para estructurar código. Claro que puede que el algoritmo sea lo bastante complejo como para que necesitemos describir sus diferentes partes. En este caso, el mejor refactor es extraer esas partes a métodos privados con nombres descriptivos, en lugar de usar comentarios:

1 public function calculateFee(Request $dataToCalculate)
2 {
3     $this->normalizeAmountsToTheSameCurrency($dataToCalculate);
4     $initialCalculation = $this->performInitialCalculation($dataToCalcu\
5 late);
6     $transformedResponse = $this->applyTransformation($initialCalculati\
7 on);
8 }

De este modo el código está estructurado y documentado.

Comentarios sobre valores válidos. Consideremos este código:

1 // Valid values: started, paused, running, terminated
2 public function updateStatus(string $newStatus): void
3 {
4     $this->checkValidStatus($newStatus);
5     $this->status = $newStatus;
6 }

El comentario delimita los valores aceptables para un parámetro, pero no fuerza ninguno de ellos. Eso tenemos que hacerlo mediante una cláusula de guarda. ¿Hay una forma mejor de hacerlo?

Por supuesto: utilizar un enumerable.

 1 class Status
 2 {
 3     private const STARTED = 'started';
 4     private const PAUSED = 'paused';
 5     private const RUNNING = 'running';
 6     private const TERMINATED = 'terminated';
 7     
 8     private $value;
 9     
10     private function __construct(string $status)
11     {
12         $this->checkValidStatus($status);
13         $this->status = $status;    
14     }
15     
16     public static function fromString(string $status): Status
17     {
18         return new self($status);
19     }
20     
21     public static function started(): Status
22     {
23         return new self(self::STARTED);
24     }
25     
26     //...
27 }

Lo que permite eliminar el comentario, a la vez que tener una implementación más limpia y coherente:

1 public function updateStatus(Status $newStatus): void
2 {
3     $this->status = $newStatus;
4 }

Código comentado

En alguna parte he escuchado o leído algo así como “código comentado: código borrado”. El código comentado debería desaparecer. Lo más seguro es que ya nadie se acuerde de por qué estaba ese código ahí, para empezar, y por qué sigue aunque sea escondido en un comentario.

Si es necesario recuperarlo (spoiler: no lo será) siempre nos queda el control de versiones.

Excepciones: a veces se puede usar la técnica de comentar un código para desactivarlo temporalmente. En ese caso, deberíamos explicar esa decisión también en el mismo comentario. Mucho mejor que eso es utilizar alguna técnica de feature flag. Existen librerías en todos los lenguajes para gestionar feature flags, pero en muchos casos podemos introducer alguna variable que sea fácil de cambiar:

1 if ($useNewCode === true) {
2     $this->newCode();
3 } else {
4     $this->oldCode();
5 }

Comentarios que podríamos conservar… o no

Comentarios que explican decisiones

Los buenos comentarios deberían explicar por qué tomamos alguna decisión que no podemos expresar mediante el propio código y que, por su naturaleza, podríamos considerar como independientes de la implementación concreta que el código realiza. Es decir, no deberíamos escribir comentarios que expliquen cómo es el código, que es algo que ya podemos ver, sino que expliquen por qué es así.

Lo normal es que estos comentarios sean pocos, pero relevantes, lo cual los pone en una buena situación para realizar un mantenimiento activo de los mismos.

Obviamente, corremos el riesgo de que los comentarios se hagan obsoletos si olvidamos actualizarlos cuando sea necesario. Por eso la importancia de que no estén “acoplados” a la implementación en código.

Un ejemplo de comentario relevante podría ser este:

1 // We apply taxes to conform the procedure stated in law RD 2018/09
2 public function applyTaxes(Money $totalAmountBeforeTaxes): Money
3 {
4     //... some code here
5 }

Este comentario es completamente independiente del código e indica una información importante que no podríamos expresar con él. Si en un momento dado cambia la legislación y debemos aplicar otra normativa, podemos cambiar el comentario.

Aunque, a decir verdad, podríamos llegar a expresarlo en código. A grandes rasgos:

 1 interface Taxes
 2 {
 3     public function apply(Money $amountBeforeTaxes): Money;
 4 }
 5 
 6 class RD201809Taxes implements Taxes
 7 {
 8     public function apply(Money $amountBeforeTaxes): Money
 9     {
10         // ... some code here
11     }
12 }
13 
14 
15 class RD201821Taxes implements Taxes
16 {
17     public function apply(Money $amountBeforeTaxes): Money
18     {
19         // ... some code here
20     }
21 }

Dudas razonables

Comentarios para el IDE

En aquellos lenguajes en los que el análisis estático por parte del IDE no pueda interpretar algunas cosas, añadir comentarios en forma de anotaciones puede suponer una ayuda para el IDE. En algunos casos, gracias a eso nos avisa de problemas potenciales antes de integrar los cambios.

No debería ser una práctica común, pero es un compromiso aceptable. Por ejemplo, en PHP era frecuente indicar el tipo de las propiedades de los objetos y otras variables con comentarios, ya que el lenguaje no permitía hacerlo en código.

1 class Status
2 {
3     /** string **/
4     private $value;
5 }

Esto se introdujo en la versión 7.4:

1 class Status
2 {
3     private string $value;
4 }

En otros lenguajes, estas características estaban presentes desde mucho antes.

Las seis preguntas

El framework de las seis preguntas se utiliza en algunas disciplinas para determinar si una fuente proporciona información completa. Estas preguntas se pueden usar para decidir qué comentar en un código y qué no es necesario:

• ¿Cuándo se ha escrito el código?: Esta información la encontramos fácilmente en el sistema de control de versiones. No hay que añadirla como comentario. El único caso en que se me ocurre que podría ser útil es cuando mudamos un repositorio a un servidor diferente, ya que se puede perder la información.
• ¿Quién ha escrito el código?: Aplica lo mismo que en la pregunta anterior, es información que nos proporciona el sistema de control de versiones, de una forma mucho más precisa.
• ¿Dónde está el código?: Aplicado a la paquetización del código, básicamente es una información que o bien se declara de forma explícita, o bien el lenguaje se encarga de reportarnos en caso de errores. Por tanto, tampoco parece necesario establecerlo en un comentario.
• ¿Qué hace el código?: La respuesta corta es que el código ya dice lo que hace, pero con frecuencia eso no queda tan claro porque los nombres están mal escogidos o la estructura del código lleva a confusión. Eso podría llevarnos a plantear la necesidad de indicarlo en un comentario. Pero antes de ellos, lo apropiado sería reflexionar sobre cómo explicitar la intención de ese fragmento de código usando un buen nombre. Y, de todos modos, la mejor forma de documentar lo que hace un código es mediante un test.
• ¿Cómo hace el código lo que hace?: De nuevo, una vez que sabemos lo que hace un código, el cómo debería ser el código en sí. Ahora bien, hay algunos casos en los que es recomendable añadir comentarios. Uno de esos casos es el uso de algoritmos bien conocidos, que tienen nombre. En esa situación, es muy buena idea hacerlo explícito. Otro caso podría ser el de documentar distintos pasos en un algoritmo, aunque para ello suele ser mejor extraerlos a sus propios métodos.
• ¿Por qué hace el código lo que hace?: Finalmente, esta es una pregunta que solo podemos contestar nosotras: las personas responsables de ese conocimiento. Y esa explicación debe aparecer como comentario.

Resumen del capítulo

Los comentarios en el código tienen una utilidad limitada y, con frecuencia, se vuelven mentirosos y no resultan de ayuda para comprender lo que nuestro código hace, pudiendo incluso llevarnos a confusión si les hacemos caso.

Si introduces un comentario, debes responsabilizarte de su ciclo de vida: actualizarlo cuando cambie el código al que hace referencia. Borrarlo si ya no sirve de nada.

En lugar de usar comentarios es preferible trabajar en mejores nombres para los símbolos (variables, constantes, clases, métodos, funciones…), estructurar mejor el código en funciones o métodos que expresen su intención.

Si necesitamos documentar cómo funciona algo y cómo usarlo, es mucho mejor introducir tests, los cuales proporcionan una documentación viva.

Por otro lado, los comentarios que sí pueden permanecer suelen referirse a aspectos que no podemos expresar fácilmente con código, como puede ser explicar los motivos para hacer algo de una forma concreta. Aún así, debes asegurarte de mantenerlos al día.

Capítulo 2. El nombre de la cosa

En el que Adso y Guillermo… ejem, en el que discutimos sobre la necesidad de poner los nombres adecuados a las cosas del código, a fin de que se entienda qué demonios pasaba en aquel momento por nuestra cabeza, o la de la autora del código que tenemos que intervenir.

Probablemente en ningún lugar como el código los nombres configuran la realidad. Escribir código implica establecer decenas de nombres cada día, para identificar conceptos y procesos. Una mala elección de nombre puede condicionar nuestra forma de ver un problema de negocio. Un nombre ambiguo puede llevarnos a entrar en un callejón sin salida, ahora o en un futuro no muy lejano. Pero un nombre bien escogido puede ahorrarnos tiempo, dinero y dificultades.

Notas de la segunda edición

En este capítulo hemos cambiado los ejemplos para que los nombres originales sean mucho menos expresivos. De este modo, se entiende mejor la necesidad del refactor, y también se entiende mejor lo que hace la clase Calculator que hemos usado como ejercicio.

Símbolos con nombres

Un trozo de código debería poder leerse como una especie de narrativa, en la cual cada palabra expresase de forma unívoca un significado. También de forma ubicua y coherente, es decir, que el mismo símbolo debería representar el mismo concepto en todas partes del código.

¿Cuándo refactorizar nombres?

La regla de oro es muy sencilla: cada vez que al leer una línea de código tenemos que pararnos a pensar qué está diciendo lo más probable sea que debamos cambiar algún nombre.

Este es un ejemplo de un código en el que nos encontramos con unos cuantos problemas de nombres, algunos son evidentes y otros no tanto:

 1 class Item {
 2     private $val;
 3 
 4     public function __construct($val) {
 5         $this->val = $val;
 6     }
 7 
 8     public function getVal() {
 9         return $this->val;
10     }
11 }
12 
13 class Calculator {
14     private $rate1;
15     private $rate2;
16 
17     public function __construct($rate1, $rate2) {
18         $this->rate1 = $rate1;
19         $this->rate2 = $rate2;
20     }
21 
22     public function calc($item) {
23         $val = $item->getVal();
24         $val = $this->applyRate2($val);
25         $val = $this->applyRate1($val);
26         return $val;
27     }
28 
29     private function applyRate2($val) {
30         return $val * (1 + $this->rate2);
31     }
32 
33     private function applyRate1($val) {
34         return $val * (1 - $this->rate1);
35     }
36 }

Por supuesto, en este ejemplo hay algunos errores más aparte de los nombres. Pero hoy solo nos ocuparemos de estos. Vamos por partes.

Nombres demasiado genéricos

Los nombres demasiado genéricos requieren el esfuerzo de interpretar el caso concreto en que se están aplicando. Además, en un plano más práctico, resulta difícil localizar una aparición específica del mismo que tenga el significado deseado.

¿De dónde vienen los nombres demasiado genéricos? Normalmente, vienen de estadios iniciales del código, en los que probablemente bastaba con ese término genérico para designar un concepto. Con el tiempo, ese concepto evoluciona y se ramifica a medida que el conocimiento de negocio avanza, pero el código puede que no lo haya hecho al mismo ritmo, con lo que llega un momento en que este no es reflejo del conocimiento actual que tenemos del negocio.

Calculate… what? Exactamente, ¿qué estamos calculando aquí? El código no lo refleja. Podría ocurrir, por ejemplo, que $rate1 fuese algún tipo de descuento, $rate2 podría ser una comisión o impuestos y $val parece claro que es algo así como el precio de tarifa de algún producto o servicio, sea lo que sea que vende esta empresa. Es muy posible que este método lo que haga sea calcular el precio final para el consumidor del producto. ¿Por qué no declararlo de forma explícita?

 1 class Calculator {
 2     private $rate1;
 3     private $rate2;
 4 
 5     public function __construct($rate1, $rate2) {
 6         $this->rate1 = $rate1;
 7         $this->rate2 = $rate2;
 8     }
 9 
10     public function finalPrice($item) {
11         $val = $item->getVal();
12         $val = $this->applyRate2($val);
13         $val = $this->applyRate1($val);
14         return $val;
15     }
16 
17     private function applyRate2($val) {
18         return $val * (1 + $this->rate2);
19     }
20 
21     private function applyRate1($val) {
22         return $val * (1 - $this->rate1);
23     }
24 }

Vamos a revisar los distintos nombres que se están usando en el código para representar los conceptos que se manejan en esta calculadora de precios. Puesto que tenemos bastante claro que $val es el precio del producto, podemos hacerlo explícito.

 1 class Calculator {
 2     private $rate1;
 3     private $rate2;
 4 
 5     public function __construct($rate1, $rate2) {
 6         $this->rate1 = $rate1;
 7         $this->rate2 = $rate2;
 8     }
 9 
10     public function finalPrice($item) {
11         $price = $item->getVal();
12         $price = $this->applyRate2($price);
13         $price = $this->applyRate1($price);
14         return $price;
15     }
16 
17     private function applyRate2($price) {
18         return $price * (1 + $this->rate2);
19     }
20 
21     private function applyRate1($price) {
22         return $price * (1 - $this->rate1);
23     }
24 }

La clase Item, que representa el producto o servicio que estamos vendiendo nos proporciona ese precio base e, igualmente, deberíamos hacerlo explícito.

 1 class Item {
 2     private $price;
 3 
 4     public function __construct($price) {
 5         $this->basePrice = $price;
 6     }
 7 
 8     public function basePrice() {
 9         return $this->basePrice;
10     }
11 }

Con estos cambios de nombres, debería haber quedado más claro qué es lo que está pasando.

 1 class Calculator {
 2     private $rate1;
 3     private $rate2;
 4 
 5     public function __construct($rate1, $rate2) {
 6         $this->rate1 = $rate1;
 7         $this->rate2 = $rate2;
 8     }
 9 
10     public function finalPrice($item) {
11         $price = $item->basePrice();
12         $price = $this->applyRate2($price);
13         $price = $this->applyRate1($price);
14         return $price;
15     }
16 
17     private function applyRate2($price) {
18         return $price * (1 + $this->rate2);
19     }
20 
21     private function applyRate1($price) {
22         return $price * (1 - $this->rate1);
23     }
24 }

Nombres ambiguos

Hay dos propiedades en la calculadora que tienen el mismo nombre $rate1 y $rate2.

Técnicamente, son correctos, ya que $rate nos sugiere un porcentaje o proporción, algo que podemos confirmar al leer los métodos en los que se aplican. Pero, ¿qué concepto de negocio representan?

Sabemos que se aplican dos, pero no sabemos qué representan. Uno de ellos se resta y el otro se suma. El que se resta, puede ser un descuento, mientras que el que se suma, podría tratarse de un impuesto o una comisión. Debería ser obvio que necesitamos clarificarlo.

Tras hablarlo con negocio, hemos llegado a la conclusión de $rate1 representa un descuento y $rate2 un impuesto. Lo adecuado, en este caso, será poner nombres explícitos.

 1 class Calculator {
 2     private $discount;
 3     private $tax;
 4 
 5     public function __construct($discount, $tax) {
 6         $this->discount = $discount;
 7         $this->tax = $tax;
 8     }
 9 
10     public function finalPrice($item) {
11         $price = $item->basePrice();
12         $price = $this->applyRate2($price);
13         $price = $this->applyRate1($price);
14         return $price;
15     }
16 
17     private function applyRate2($price) {
18         return $price * (1 + $this->tax);
19     }
20 
21     private function applyRate1($price) {
22         return $price * (1 - $this->discount);
23     }
24 }

Con este refactor ya hemos ganado mucho en expresividad, pero el término Rate se utiliza en varios nombres compuestos, por lo que no hemos terminado aún. El siguiente paso sería cambiar applyRate1 y applyRate2 por algo más descriptivo:

 1 class Calculator {
 2     private $discount;
 3     private $tax;
 4 
 5     public function __construct($discount, $tax) {
 6         $this->discount = $discount;
 7         $this->tax = $tax;
 8     }
 9 
10     public function finalPrice($item) {
11         $price = $item->basePrice();
12         $price = $this->applyTax($price);
13         $price = $this->applyDiscount($price);
14         return $price;
15     }
16 
17     private function applyTax($price) {
18         return $price * (1 + $this->tax);
19     }
20 
21     private function applyDiscount($price) {
22         return $price * (1 - $this->discount);
23     }
24 }

Aplicando este refactor hemos conseguido mucha más claridad y legibilidad. Incluso puede que hayamos hecho aflorar un bug. Si te fijas, se aplican los descuentos tras aplicar los impuestos. En muchos países, los impuestos se aplican sobre el precio final, por lo que deberíamos cambiar el orden de aplicación de los métodos applyTax y applyDiscount.

 1 class Calculator {
 2     private $discount;
 3     private $tax;
 4 
 5     public function __construct($discount, $tax) {
 6         $this->discount = $discount;
 7         $this->tax = $tax;
 8     }
 9 
10     public function finalPrice($item) {
11         $price = $item->basePrice();
12         $price = $this->applyDiscount($price);
13         $price = $this->applyTax($price);
14         return $price;
15     }
16 
17     private function applyTax($price) {
18         return $price * (1 + $this->tax);
19     }
20 
21     private function applyDiscount($price) {
22         return $price * (1 - $this->discount);
23     }
24 }

Esto es muy interesante porque nos demuestra como los nombres ambiguos puede llevarnos a errores de lógica. Al emplear el mismo término $rate para referirnos a dos conceptos completamente distintos, hemos podido confundirnos y aplicar los descuentos antes de los impuestos, lo que podría llevar a problemas legales o a pérdidas económicas. Ciertamente, sería posible prevenirlo con un buen test, que nos habría indicado el error cometido, pero, y si no tenemos un test que cubra ese caso concreto, ¿cómo lo detectaríamos?

Pero es que, además, al eliminar la ambigüedad de los nombres, reducimos la dificultad y el tiempo que nos llevaría interpretar el código. No solo para nosotras, sino también para cualquier persona que pueda tener que trabajar con él en el futuro.

Nombres reutilizados en el mismo scope

Aunque ahora tenemos el código en un estado mucho mejor, todavía tenemos un aspecto que no está realmente bien. La variable $price es actualizada constantemente y, no solo cambia de valor, sino que cambia de significado. En un momento dado, $price es el precio base del producto, en otro es el precio con el descuento aplicado y en otro es el precio con el impuesto aplicado.

 1 class Calculator {
 2     private $discount;
 3     private $tax;
 4 
 5     public function __construct($discount, $tax) {
 6         $this->discount = $discount;
 7         $this->tax = $tax;
 8     }
 9 
10     public function finalPrice($item) {
11         $price = $item->basePrice();
12         $price = $this->applyDiscount($price);
13         $price = $this->applyTax($price);
14         return $price;
15     }
16 
17     private function applyTax($price) {
18         return $price * (1 + $this->tax);
19     }
20 
21     private function applyDiscount($price) {
22         return $price * (1 - $this->discount);
23     }
24 }

El principal inconveniente de esta forma de programar es que tiene un coste de cambio alto en el futuro. Si hubiese que introducir algún paso nuevo en el cálculo del precio final, habría que modificar todos los lugares en los que se actualiza la variable $price. Además, el código es más difícil de comprender, ya que no es fácil saber en qué estado se encuentra $price en cada momento.

Podrías argumentar que se trata de una variable temporal y de que, en último término, lo que buscamos es el resultado final de todas las transformaciones. Por ejemplo, podríamos hacer algo así, y ni siquiera necesitaríamos la variable $price:

 1 class Calculator {
 2     private $discount;
 3     private $tax;
 4 
 5     public function __construct($discount, $tax) {
 6         $this->discount = $discount;
 7         $this->tax = $tax;
 8     }
 9 
10     public function finalPrice($item) {
11         $price = $this->applyTax(
12             $this->applyDiscount(
13                 $item->basePrice()
14             )
15         );
16         return $price;
17     }
18 
19     private function applyTax($price) {
20         return $price * (1 + $this->tax);
21     }
22 
23     private function applyDiscount($price) {
24         return $price * (1 - $this->discount);
25     }
26 }

Bien, esta solución es interesante, pero a primera vista ya parece más difícil de leer. No solo eso, al igual que la solución inicial nos vamos a encontrar con problemas en caso de que en algún momento necesitemos introducir un cambio.

De entrada, sería más sencillo bautizar cada paso del cálculo con un nombre que refleje su significado. Por ejemplo:

 1 class Calculator {
 2     private $discount;
 3     private $tax;
 4 
 5     public function __construct($discount, $tax) {
 6         $this->discount = $discount;
 7         $this->tax = $tax;
 8     }
 9 
10     public function finalPrice($item) {
11         $basePrice = $item->basePrice();
12         $discountedPrice = $this->applyDiscount($basePrice);
13         $priceAfterTax = $this->applyTax($discountedPrice);
14         return $priceAfterTax;
15     }
16 
17     private function applyTax($price) {
18         return $price * (1 + $this->tax);
19     }
20 
21     private function applyDiscount($price) {
22         return $price * (1 - $this->discount);
23     }
24 }

Más allá de los nombres: cuando aparecen conceptos

Por otro lado, este tipo de patrones en los que vamos cambiando el valor de una variable con cálculos que la toman como argumento de entrada, nos debería sugerir la presencia de un concepto que estaría mejor representado con un objeto. Como podemos ver, todas las operaciones se realizan sobre un precio, por lo que podríamos encapsularlo en un objeto Price. Y una vez que tenemos un objeto, lo más adecuado sería que éste se encargase de aplicar los descuentos y los impuestos.

 1 class Price {
 2     private $amount;
 3 
 4     public function __construct($amount) {
 5         $this->amount = $amount;
 6     }
 7 
 8     public function applyTax($tax) {
 9         $this->amount *= (1 + $tax);
10     }
11 
12     public function applyDiscount($discount) {
13         $this->amount *= (1 - $discount);
14     }
15 
16     public function->amount() {
17         return $this->amount;
18     }
19 }
20 
21 class Calculator {
22     private $discount;
23     private $tax;
24 
25     public function __construct($discount, $tax) {
26         $this->discount = $discount;
27         $this->tax = $tax;
28     }
29 
30     public function finalPrice($item) {
31         $price = new Price($item->basePrice());
32         $price->applyDiscount($this->discount);
33         $price->applyTax($this->tax);
34         return $price->amount();
35     }
36 }

Este refactor que acabamos de mostrar va más allá del alcance de este capítulo, pero nos ha servido para mostrar que cuando mejoramos los nombres, es muy fácil que afloren conceptos interesantes que no teníamos bien representandos con valores primitivos. En capítulos posteriores examinaremos cómo podemos introducir estos conceptos en nuestro código.

Tipo de palabra inadecuada

Los símbolos que, de algún modo, contradicen el concepto que representan son más difíciles de procesar, generalmente porque provocan una expectativa que no se cumple y, por tanto, debemos re-evaluar lo que estamos leyendo. Por ejemplo:

• Una acción debería representarse siempre mediante un verbo.
• Un concepto, mediante un sustantivo.

A su vez, nunca nos sobran los adjetivos para precisar el significado del sustantivo, por lo que los nombres compuestos nos ayudan a representar con mayor precisión las cosas.

Volvamos al ejemplo. Calculator parece un buen nombre. PriceCalculator sería aún mejor, ya que hace explícito el hecho de que calcula precios. Es un sustantivo, por lo que se deduce que es un actor que hace algo. Veámosla como interface:

1 interface PriceCalculator {
2     public finalPrice(Item $item): float;
3 }

Obviamente, este refactor es un poco más arriesgado. Vamos a tocar una interfaz pública, pero también es verdad que con los IDE modernos este tipo de cambios es razonablemente seguro.

finalPrice es un sustantivo, pero en realidad ¿no representa una acción? ¿No sería mejor calculateFinalPrice?

1 interface PriceCalculator {
2     public calculateFinalPrice(Item $item): float;
3 }

Por un lado, es cierto que parece más imperativo. Estamos diciendo algo así como: “Calculadora: calcula el precio final”. No deja lugar a dudas sobre lo que hace. En el lado negativo, resulta un nombre redundante, a la par que largo.

Pero antes… Volvamos un momento a la clase. PriceCalculator, ¿es un actor o una acción? A veces tendemos a ver los objetos como representaciones de objetos del mundo real. Sin embargo, podemos representar acciones y otros conceptos con objetos en el código. Esta forma de verlo puede cambiar por completo nuestra manera de hacer las cosas.

Supongamos entonces, que consideramos que PriceCalculator no es una cosa, sino una acción:

1 interface CalculatePrice {
2     public calculateFinalPrice(Product $product): float;
3 }

Tal y como está ahora, expresar ciertas cosas resulta extraño:

1 $calculatePrice = new CalculatePrice();
2 
3 $calculatePrice->calculateFinalPrice($product);

Pero podemos imaginarlo de otra forma mucho más fluida:

1 $calculatePrice = new CalculatePrice();
2 
3 $calculatePrice->finalForProduct($product);

Lo que nos deja con esta interfaz:

1 interface CalculatePrice {
2     public finalForProduct(Product $product): float;
3 }

Este cambio de nombre resulta interesante, pero también tenemos que valorarlo en su contexto. Que los objetos tengan nombres de acciones puede ser muy válido para representar casos de uso, pero no tanto para representar entidades de negocio. En este caso, si entendemos CalculatePrice como una entidad de negocio, PriceCalculator es un nombre mucho más adecuado.

Números mágicos

A veces no se trata estrictamente de refactorizar nombres, sino de bautizar elementos que están presentes en nuestro código en forma de valores abstractos que tienen un valor de negocio que no ha sido hecho explícito.

Poniéndoles un nombre, lo hacemos. Lo que antes era:

1 $vatAmount = $amountBeforeTaxes * .21;

En la línea anterior, .21 es un número mágico. No sabemos qué significa, pero podemos intuir que se trata de un impuesto y deberíamos hacerlo explícito.

Después:

1 const VAT_RATE = .21;
2 $vatAmount = $amountBeforeTaxes * VAT_RATE;

Convertir estos valores en constantes con nombre hace que su significado de negocio esté presente, sin tener que preocuparse de interpretarlo. Además, esto los hace reutilizables a lo largo de todo el código, lo que añade un plus de coherencia.

Así que, cada vez que encuentres uno de estos valores, hazte un favor y reemplázalo por una constante. Por ejemplo, los naturalmente ilegibles patrones de expresiones regulares:

1 $isValidNif = preg_match('/^[0-9XYZ]\d{7}[^\dUIOÑ]$/', $nif);
2 
3 // vs
4 
5 $isValidNif = preg_match(VALID_NIF_PATTERN, $nif);

O los patrones de formato para todo tipo de mensajes:

1 $mensaje = sprintf('¿Enviar un mensaje a %s en la dirección %s?', $user\
2 ->username(), $user->email());
3 
4 $mensaje = sprintf(CONFIRM_SEND_EMAIL_MESSAGE, $user->username(), $user\
5 ->email());

Nombres técnicos

Personalmente, me gustan poco los nombres técnicos formando parte de los nombres de variables, clases, interfaces, etc. De hecho, creo que en muchas ocasiones condicionan tanto el naming, que favorecen la creación de malos nombres.

Ya he hablado del problema de entender que los objetos en programación tienen que ser representaciones de objetos del mundo real. Esa forma de pensar nos lleva a ver todos los objetos como actores que hacen algo, cuando muchas veces son acciones.

En ocasiones, es verdad que tenemos que representar ciertas operaciones técnicas, que no todo va a ser negocio, pero eso no quiere decir que no hagamos las cosas de una manera elegante. Por ejemplo:

 1 interface BookTransformer
 2 {
 3     public function transformToJson(Book $book): string;
 4     public function transformFromJson(string $bookDto): Book;
 5 }
 6 
 7 // vs
 8 
 9 interface TransformBook
10 {
11     public function toJson(Book $book): string;
12     public function fromJson(string $bookDto): Book;
13 }

En cambio, en el dominio me choca ver cosas como:

1 class BookWasPrintedEvent implements DomainEvent
2 {
3 }
4 
5 // vs
6 
7 class BookWasPrinted implements DomainEvent
8 {
9 }

En este ejemplo, el uso del verbo en pasado debería ser suficiente para entender de un vistazo que está hablando de un evento, que no es otra cosa que un mensaje que indica que algo interesante ha ocurrido.

Es cierto que incluir algunos apellidos técnicos a nuestros nombres puede ayudarnos a localizar cosas en el IDE. Pero hay que recordar que no programamos para un IDE.

Refactor de nombres

En general, gracias a las capacidades de refactor de los IDE o incluso del Buscar/Reemplazar en proyectos, realizar refactors de nombres es bastante seguro.

Variables locales en métodos y funciones. Cambiarlas no supone ningún problema, pues no afectan a nada que ocurra fuera de su ámbito.

Propiedades y métodos privados en clases. Tampoco suponen ningún problema al no afectar a nada externo a la clase.

Interfaces públicas. Aunque es más delicado, los IDE modernos deberían ayudarnos a realizarlos sin mayores problemas. La mayor dificultad me la he encontrado al cambiar nombres de clases, puesto que el IDE aunque localiza y cambia correctamente sus usos, no siempre identifica objetos relacionados, como los tests.

El coste de un mal nombre

Imaginemos un sistema de gestión de bibliotecas que, inicialmente, se creó para gestionar libros. Simplificando muchísimo, aquí tenemos un concepto clave del negocio:

1 class Book
2 {
3     private $id;
4     private $title;
5     private $author;
6     private $editor;
7     private $year;
8     private $city;
9 }

Con el tiempo la biblioteca pasó a gestionar revistas. Las revistas tienen número, pero tal vez en su momento se pensó que no sería necesario desarrollar una especialización:

 1 class Book
 2 {
 3     private $id;
 4     private $title;
 5     private $author;
 6     private $editor;
 7     private $year;
 8     private $city;
 9     private $issue;
10 }

Y aquí comienza un desastre que solo se detecta mucho tiempo después y que puede suponer una sangría, quizá lenta pero constante, de tiempo, recursos y, en último término, dinero para los equipos y empresas.

La modificación de la clase Book hizo que esta pasara a representar dos conceptos distintos, pero quizá se consideró que era una ambigüedad manejable: un compromiso aceptable.

Claro que la biblioteca siguió evolucionando y con el avance tecnológico comenzó a introducir nuevos tipos de objetos, como CD, DVD, libros electrónicos, y un largo etcétera. En este punto, el conocimiento que maneja negocio y su representación en el código se han alejado tanto que el código se ha convertido en una pesadilla: ¿cómo sabemos si Book se refiere a un libro físico, a uno electrónico, a una película en DVD, a un juego en CD? Solo podemos saberlo examinando el contenido de cada objeto Book. Es decir: el código nos está obligando a pararnos a pensar para entenderlo. Necesitamos refactorizar y reescribir.

Es cierto que, dejando aparte el contenido, todos los objetos culturales conservados en una biblioteca comparten ese carácter de objeto cultural o soporte de contenidos. CulturalObject se nos antoja un nombre demasiado forzado, pero Media resulta bastante manejable:

1 class Media
2 {
3     private $id;
4     private $signature;
5     private $registeredSince;
6     private $status;
7 }

Media representaría a los soportes de contenidos archivados en la biblioteca y que contendría propiedades como un número de registro (el id), la signatura topográfica (que nos comunica su ubicación física) y otros detalles relacionados con la actividad de archivo, préstamo, etcétera.

Pero esa clase tendría especializaciones que representan tipos de medios específicos, con sus propiedades y comportamientos propios.

 1 class Book extends Media
 2 {
 3 }
 4 
 5 class Review extends Media
 6 {
 7 }
 8 
 9 class ElectronicBook extends Media
10 {
11 }
12 
13 class Movie extends Media
14 {
15 } 

Podríamos desarrollar más el conocimiento de negocio en el código, añadiendo interfaces. Por ejemplo, la gestión del préstamo:

1 interface Lendable
2 {
3     public function lend(User $user): void;
4     public function return(DateTimeInterface $date): void;
5 }

Pero el resumen es que el hecho de no haber ido reflejando la evolución del conocimiento del negocio en el código nos lleva a tener un sobre-coste en forma de:

• El tiempo y recursos necesarios para actualizar el desarrollo a través de reescrituras.
• El tiempo y recursos necesarios para mantener el software cuando surgen problemas derivados de la mala representación del conocimiento.
• Las pérdidas por no ingresos debidos a la dificultad del software de adaptarse a las necesidades cambiantes del negocio.

Por esto, preocúpate por poner buenos nombres y mantenerlos al día. Va en ello tu salario.

Capítulo 3. Acondiciona las condicionales

En el que decidimos cómo hacer que las decisiones que el código toma sean más comprensibles y fáciles de mantener en el futuro, porque al fin y a la postre todo en esta vida es decidir. El caso es saber cuando tomar las decisiones y comprender bien sus condiciones y sus consecuencias.

Notas de la segunda edición

En este capítulo, como en otros, hemos mejorado los ejemplos y corregido algunas explicaciones para que sean más claras. Ahora la mayor parte de ejemplos tienen más sentido y ofrecen más contexto. Asímismo hemos incluido algunas propuestas nuevas.

La complejidad de decidir

Es bastante obvio que si hay algo que añade complejidad a un software es la toma de decisiones y, por tanto, las estructuras condicionales con las que la expresamos.

Estas estructuras pueden introducir dificultades de comprensión debido a varias razones:

• La complejidad de las expresiones evaluadas, sobre todo cuando se combinan mediante operadores lógicos tres o más condiciones, lo que las hace difíciles de procesar para nosotras.
• La anidación de estructuras condicionales y la concatenación de condicionales mediante else, introduciendo múltiples flujos de ejecución.
• El desequilibrio entre las ramas en las que una rama tiene unas pocas líneas frente a la otra que esconde su propia complejidad, lo que puede llevar a pasar por alto la rama corta y dificulta la lectura de la rama larga al introducir un nuevo nivel de indentación.

¿Cuándo refactorizar condicionales?

En general, como regla práctica, hay que refactorizar condicionales cuando su lectura no nos deja claro cuál es su significado. Esto se aplica en las dos partes de la estructura:

• La expresión condicional: qué define lo que tiene que pasar para que el flujo se dirija por una o por otra rama.
• Las ramas: las diferentes acciones que se deben ejecutar en caso de cumplirse o no la condición.

También podemos aplicar alguna de las reglas de object calisthenics:

Aplanar niveles de indentación: cuanto menos anidamiento en el código, más fácil de leer es porque indica que no estamos mezclando niveles de abstracción. El objetivo sería tener un solo nivel de indentación en cada método o función.

Eliminar else: en muchos casos, es posible eliminar ramas alternativas, bien directamente, bien encapsulando toda la estructura en un método o función.

Vamos a ver como podemos proceder a refactorizar condicionales de una forma sistemática.

La rama corta primero

Si una estructura condicional nos lleva por una rama muy corta en caso de cumplirse y por una muy larga en el caso contrario, se recomienda que la rama corta sea la primera, para evitar que pase desapercibida. Por ejemplo, este fragmento tan feo:

 1 function obtainPaymentMethod(Order $order): PaymentMethod {
 2     $selectedPaymentMethod = $order->getSelectedPaymentMethod();
 3     if ($selectedPaymentMethod === null) {
 4         $logger = Logger::getInstance();
 5         $logger->debug("Medio de pago desconocido");
 6         if ($order->getDestinationCountry() == Country::FRANCE && $orde\
 7 r->id() < 745) {
 8             $paymentMethod = PaymentTypes::PAYPAL;
 9         } else {
10             $paymentMethod = new DefaultPaymentMethod();
11         }
12     } else {
13         $paymentMethod = $selectedPaymentMethod;
14     }
15     
16     return $paymentMethod;
17 }

Podría reescribirse así y ahora es más fácil ver la rama corta. Esto nos va a encaminar hacia otras refactorizaciones que veremos más adelante:

 1 function obtainPaymentMethod(Order $order): PaymentMethod {
 2     $selectedPaymentMethod = $order->getSelectedPaymentMethod();
 3     if ($selectedPaymentMethod !== null) {
 4         $paymentMethod = $selectedPaymentMethod;
 5     } else {
 6         $logger = Logger::getInstance();
 7         $logger->debug("Medio de pago desconocido");
 8         if ($order->getDestinationCountry() == Country::FRANCE && $orde\
 9 r->id() < 745) {
10             $paymentMethod = PaymentTypes::PAYPAL;
11         } else {
12             $paymentMethod = new DefaultPaymentMethod();
13         }
14     }
15     
16     return $paymentMethod;
17 }

Return early

Si estamos dentro de una función o método y podemos hacer el retorno desde dentro de una rama es preferible hacerlo. Con eso podemos evitar la cláusula else y hacer que el código vuelva al nivel de indentación anterior, lo que facilitará la lectura. Veámoslo aplicado al ejemplo anterior:

 1 function obtainPaymentMethod(Order $order): PaymentMethod {
 2     $selectedPaymentMethod = $order->getSelectedPaymentMethod();
 3     if ($selectedPaymentMethod !== null) {
 4         $paymentMethod = $selectedPaymentMethod;
 5         
 6         return $paymentMethod;
 7     } else {
 8         $logger = Logger::getInstance();
 9         $logger->debug("Medio de pago desconocido");
10         if ($order->getDestinationCountry() == Country::FRANCE && $orde\
11 r->id() < 745) {
12             $paymentMethod = PaymentTypes::PAYPAL;
13         } else {
14             $paymentMethod = new DefaultPaymentMethod();
15         }
16     }
17     
18     return $paymentMethod;
19 }

No hace falta mantener la variable temporal, pues podemos devolver directamente la respuesta obtenida:

 1 function obtainPaymentMethod(Order $order): PaymentMethod {
 2     $selectedPaymentMethod = $order->getSelectedPaymentMethod();
 3     if ($selectedPaymentMethod !== null) {
 4         return $selectedPaymentMethod;
 5     } else {
 6         $logger = Logger::getInstance();
 7         $logger->debug("Medio de pago desconocido");
 8         if ($order->getDestinationCountry() == Country::FRANCE && $orde\
 9 r->id() < 745) {
10             $paymentMethod = PaymentTypes::PAYPAL;
11         } else {
12             $paymentMethod = new DefaultPaymentMethod();
13         }
14         
15         return $paymentMethod;
16     }
17 }

Y, por último, podemos eliminar la cláusula else y dejarlo así.

 1 function obtainPaymentMethod(Order $order): PaymentMethod {
 2     $selectedPaymentMethod = $order->getSelectedPaymentMethod();
 3     if ($selectedPaymentMethod !== null) {
 4         return $selectedPaymentMethod;
 5     }
 6     
 7     $logger = Logger::getInstance();
 8     $logger->debug("Medio de pago desconocido");
 9     if ($order->getDestinationCountry() == Country::FRANCE && $order->i\
10 d() < 745) {
11         $paymentMethod = PaymentTypes::PAYPAL;
12     } else {
13         $paymentMethod = new DefaultPaymentMethod();
14     }
15     
16     return $paymentMethod;
17 }

Aplicando el mismo principio, reducimos la complejidad aportada por la condicional final, retornando directamente y eliminando tanto else como las variables temporales:

 1 function obtainPaymentMethod(Order $order): PaymentMethod {
 2     $selectedPaymentMethod = $order->getSelectedPaymentMethod();
 3     if ($selectedPaymentMethod !== null) {
 4         return $selectedPaymentMethod;
 5     }
 6     
 7     $logger = Logger::getInstance();
 8     $logger->debug("Medio de pago desconocido");
 9     
10     if ($order->getDestinationCountry() == Country::FRANCE && $order->i\
11 d() < 745) {
12         return PaymentTypes::PAYPAL;
13     }
14     
15     return new DefaultPaymentMethod();
16 }

El contexto habitual de esta técnica es la de tratar casos particulares o que sean obvios en los primeros pasos del algoritmo, volviendo al flujo principal cuanto antes, de modo que solo recibe aquellos casos a los que se aplica realmente. Una variante de esta idea consiste en la introducción de las cláusulas de guarda, que veremos a continuación.

Cláusulas de guarda

En muchas ocasiones, cuando los datos tienen que ser validados antes de operar con ellos, podemos encapsular esas condiciones en forma de cláusulas de guarda. Estas cláusulas de guarda, también se conocen como aserciones, o precondiciones. Si los parámetros recibidos no las cumplen, el método o función falla, generalmente, lanzando excepciones.

1 public function applyDiscount($parameter)
2 {
3     if ($parameter > 100 || $parameter < 0) {
4         throw new OutOfRangeException(sprintf('Parameter should be betw\
5 een 0 and 100 (inc), %s provided.', $parameter));
6     }
7     
8     // further processing
9 }

Extraemos toda la estructura a un método privado:

 1 public function applyDiscount($parameter)
 2 {
 3     $this->checkParameterIsInRange($parameter);
 4         
 5     // further processing
 6 }
 7 
 8 private function checkParameterIsInRange($parameter) 
 9 {
10     if ($parameter > 100 || $parameter < 0) {
11         throw new OutOfRangeException(sprintf('Parameter should be betw\
12 een 0 and 100 (inc), %s provided.', $parameter));
13     }
14 }

La lógica bajo este tipo de cláusulas es que si no salta ninguna excepción, quiere decir que $parameter ha superado todas las validaciones y lo puedes usar con confianza. La ventaja es que las reglas de validación definidas con estas técnicas resultan muy expresivas, ocultando los detalles técnicos en los métodos extraídos.

Una alternativa es usar una librería de aserciones, lo que nos permite hacer lo mismo de una forma aún más limpia y reutilizable. Si la aserción no se cumple, se tirará una excepción:

1 public function applyDiscount($parameter)
2 {
3     Assert::betweenExclusive($parameter, 0, 100);
4         
5     // further processing
6 }

Una limitación de las aserciones que debemos tener en cuenta es que no sirven para control de flujo. Esto es, las aserciones fallan con una excepción, interrumpiendo la ejecución del programa, que así puede comunicar al módulo llamante una circunstancia que impide continuar. Por eso, las aserciones son ideales para validar precondiciones.

En el caso de necesitar una alternativa si el parámetro no cumple los requisitos, utilizaremos condicionales. Por ejemplo, si el parámetro excede los límites queremos que se ajuste al límite que ha superado, en vez de fallar:

 1 $parameter = $this->checkTheParameterIsInRange($parameter);
 2 
 3 // further processing
 4 
 5 private function checkTheParameterIsInRange(int $parameter)
 6 {
 7     if ($parameter > 100) {
 8         return 100;
 9     }
10     
11     if ($parameter < 0) {
12         return 0;
13     }
14     
15     return $parameter;
16 }

Finalmente, ten en cuenta que el tipado ya es una guarda en sí misma, por lo que no necesitas verificar el tipo de un parámetro si ya lo has tipado correctamente.

Preferir condiciones afirmativas

Diversos estudios han mostrado que las frases afirmativas son más fáciles de entender que las negativas, por lo que siempre que sea posible deberíamos intentar convertir la condición en afirmativa ya sea invirtiéndola, ya sea encapsulándola de modo que se exprese de manera afirmativa. Con frecuencia, además, la particular sintaxis de la negación puede hacerlas poco visibles:

1 if (!$selectedPaymentMethod) {
2     return $selectedPaymentMethod;
3 } 

En uno de los ejemplos anteriores habíamos llegado a la siguiente construcción invirtiendo la condicional lo que resultó en una doble negación que puede hacerse difícil de leer:

1 if (null !== $selectedPaymentMethod) {
2     return $selectedPaymentMethod;
3 } 

Nosotros lo que queremos es devolver el método de pago en caso de tener uno seleccionado:

1 if ($selectedPaymentMethod) {
2     return $selectedPaymentMethod;
3 } 

Una forma alternativa, si la condición es compleja o simplemente difícil de entender tal cual es encapsularla en un método:

1 if ($this->userHasSelectedAPaymentMethod($selectedPaymentMethod)) {
2     return $selectedPaymentMethod;
3 } 
4 
5 function userHasSelectedAPaymentMethod($selectedPaymentMethod)
6 {
7     return null !== $selectedPaymentMethod;
8 }

Encapsula expresiones complejas en métodos o funciones

La idea es encapsular expresiones condicionales complejas en funciones o métodos, de modo que su nombre describa el significado de la expresión condicional, manteniendo ocultos los detalles escabrosos de la misma. Esto puede hacerse de forma global o por partes.

Justo en el apartado anterior hemos visto un ejemplo de esto mismo, haciendo explícito el significado de una expresión condicional difícil de leer.

Veamos otro caso en el mismo ejemplo: la extraña condicional que selecciona el método de pago en función del país de destino y el número de pedido. Posiblemente, algún apaño para resolver un problema concreto en los primeros pasos de la empresa.

 1 function obtainPaymentMethod(Order $order): PaymentMethod {
 2     $selectedPaymentMethod = $order->getSelectedPaymentMethod();
 3     if ($selectedPaymentMethod !== null) {
 4         return $selectedPaymentMethod;
 5     }
 6     
 7     $logger = Logger::getInstance();
 8     $logger->debug("Medio de pago desconocido");
 9     
10     if ($order->getDestinationCountry() == Country::FRANCE && $order->i\
11 d() < 745) {
12         return PaymentTypes::PAYPAL;
13     }
14     
15     return new DefaultPaymentMethod();
16 }

Se podría encapsular la condición en un método que sea un poco más explicativo:

 1 function obtainPaymentMethod(Order $order): PaymentMethod {
 2     $selectedPaymentMethod = $order->getSelectedPaymentMethod();
 3     if ($selectedPaymentMethod !== null) {
 4         return $selectedPaymentMethod;
 5     }
 6     
 7     $logger = Logger::getInstance();
 8     $logger->debug("Medio de pago desconocido");
 9     
10     if ($this->isLegacyOrderWithDestinationFrance($order)) {
11         return PaymentTypes::PAYPAL;
12     }
13     
14     return new DefaultPaymentMethod();
15 }

Y el método encapsulado sería algo así:

1 private function isLegacyOrderWithDestinationFrance($order)
2 {
3     return $order->getDestinationCountry() == Country::FRANCE && $order\
4 ->id() < 745;
5 }

Encapsula ramas en métodos o funciones

Consiste en encapsular todo el bloque de código de cada rama de ejecución en su propio método, de modo que el nombre nos indique qué hace. Esto nos deja las ramas de la estructura condicional al mismo nivel y expresando lo que hacen de manera explícita y global. En los métodos extraídos podemos seguir aplicando refactors progresivos hasta que ya no sea necesario.

Este fragmento de código, que está bastante limpio, podría clarificarse un poco, encapsulando tanto las condiciones como la rama:

 1 if ($productStatus == OrderStatuses::PROVIDER_PENDING ||
 2     $productStatus == OrderStatuses::PENDING ||
 3     $productStatus == OrderStatuses::WAITING_FOR_PAYMENT
 4 ) {
 5     if ($paymentMethod == PaymentTypes::BANK_TRANSFER) {
 6         return 'pendiente de transferencia';
 7     }
 8     if ($paymentMethod == PaymentTypes::PAYPAL || $paymentMethod == Pay\
 9 mentTypes::CREDIT_CARD) {
10         return 'pago a crédito';
11     }
12     if ($this->paymentMethods->hasSelectedDebitCard()) {
13         return 'pago a débito';
14     }
15     if (!$this->paymentMethods->requiresAuthorization()) {
16         return 'pago no requiere autorización';
17     }
18 }

Veamos como:

 1 if ($this->productIsInPendingStatus($productStatus)) {
 2     return $this->reportForProductInPendingStatus($paymentMethod);
 3 }
 4 
 5 private function productIsInPendingStatus($productStatus)
 6 {
 7     return ($productStatus == OrderStatuses::PROVIDER_PENDING ||
 8     $productStatus == OrderStatuses::PENDING ||
 9     $productStatus == OrderStatuses::WAITING_FOR_PAYMENT);
10 }
11 
12 private function reportForProductInPendingStatus(paymentMethod)
13 {
14     if ($paymentMethod == PaymentTypes::BANK_TRANSFER) {
15         return 'pendiente de transferencia';
16     }
17     if ($paymentMethod == PaymentTypes::PAYPAL || $paymentMethod == Pay\
18 mentTypes::CREDIT_CARD) {
19         return 'pago a crédito';
20     }
21     if ($this->paymentMethods->hasSelectedDebitCard()) {
22         return 'pago a débito';
23     }
24     if (!$this->paymentMethods->requiresAuthorization()) {
25         return 'pago no requiere autorización';
26     }
27 }

De ese modo, la complejidad queda oculta en los métodos y el cuerpo principal se entiende fácilmente. Ya es cuestión nuestra si necesitamos seguir el refactor dentro de los métodos privados que acabamos de crear.

Equalize branches

Si hacemos esto en todas las ramas de una condicional o de un switch las dejaremos todas al mismo nivel, lo que facilita su lectura.

Reemplaza if…elseif sucesivos con switch

En muchos casos, sucesiones de if o if…else quedarán mejor expresados mediante una estructura switch. Por ejemplo, siguiendo con el ejemplo anterior, este método que hemos extraído:

 1 private function reportForProductInPendingStatus(paymentMethod)
 2 {
 3     if ($paymentMethod == PaymentTypes::BANK_TRANSFER) {
 4         return 'pendiente de transferencia';
 5     }
 6     if ($paymentMethod == PaymentTypes::PAYPAL || $paymentMethod == Pay\
 7 mentTypes::CREDIT_CARD) {
 8         return 'pago a crédito';
 9     }
10     if ($this->paymentMethods->hasSelectedDebitCard()) {
11         return 'pago a débito';
12     }
13     if (!$this->paymentMethods->requiresAuthorization()) {
14         return 'pago no requiere autorización';
15     }
16 }

Podría convertirse en algo así:

 1 private function reportForProductInPendingStatus(paymentMethod)
 2 {
 3     switch $paymentMethod {
 4         case PaymentTypes::BANK_TRANSFER:
 5             return 'pendiente de transferencia';
 6         case PaymentTypes::PAYPAL:
 7         case PaymentTypes::CREDIT_CARD:
 8             return 'pago a crédito';
 9     }
10     
11     if ($this->paymentMethods->hasSelectedDebitCard()) {
12         return 'pago a débito';
13     }
14     if (!$this->paymentMethods->requiresAuthorization()) {
15         return 'pago no requiere autorización';
16     }
17 }

Sustituir if por el operador ternario

A veces, un operador ternario puede ser más legible que una condicional:

 1 function selectElement(Criteria $criteria, Desirability $desirability)
 2 {
 3     $found = false;
 4     
 5     $elements = $this->getElements($criteria);
 6     
 7     foreach($elements as $element) {
 8         if (!$found && $this->isDesired($element, $desirability)) {
 9             $result = $element;
10             $found = true;
11         }
12     }
13     if (!$found) {
14         $result = null;
15     }
16     
17     return $result;
18 }

Realmente las últimas líneas pueden expresarse en una sola y queda más claro:

 1 function selectElement(Criteria $criteria, Desirability $desirability)
 2 {
 3     $found = false;
 4     
 5     $elements = $this->getElements($criteria);
 6     
 7     foreach($elements as $element) {
 8         if (!$found && $this->isDesired($element, $desirability)) {
 9             $result = $element;
10             $found = true;
11         }
12     }
13     
14     return $found ? $result : null;
15 }

El operador ternario tiene sus problemas, pero, en general, es una buena solución cuando queremos expresar un cálculo que se resuelve de dos maneras según una condición. Eso sí: nunca anides operadores ternarios porque su lectura entonces se complica enormemente.

De todos modos, este ejemplo concreto de código puede mejorar mucho. Si nos fijamos, el primer elemento encontrado ya nos basta como respuesta, por lo que se podría devolver inmediatamente. No necesitamos ninguna variable temporal, ni una doble condición. Este tipo de refactor lo veremos en el capítulo sobre return early.

 1 function selectElement(Criteria $criteria, Desirability $desirability)
 2 { 
 3     foreach($this->getElements($criteria) as $element) {
 4         if ($this->isDesired($element, $desirability)) {
 5             return $element;
 6         }
 7     }
 8     
 9     return null;
10 }

Solo un if por método

Christian Clausen en Five Lines of Code propone un refactor para condicionales que puede ser muy interesante. Con frecuencia, una estructura condicional indica que una función está haciendo varias cosas distintas. Por tanto, lo que propone es que cada método haga solo una cosa, y que, por tanto, solo tenga un if que sería la primera línea. Si hay más de uno, separamos en métodos distintos.

 1 function obtainPaymentMethod(Order $order): PaymentMethod {
 2     $selectedPaymentMethod = $order->getSelectedPaymentMethod();
 3     if ($selectedPaymentMethod !== null) {
 4         return $selectedPaymentMethod;
 5     }
 6     
 7     $logger = Logger::getInstance();
 8     $logger->debug("Medio de pago desconocido");
 9     
10     if ($order->getDestinationCountry() == Country::FRANCE && $order->i\
11 d() < 745) {
12         return PaymentTypes::PAYPAL;
13     }
14     
15     return new DefaultPaymentMethod();
16 }

Podría quedar más o menos así:

 1 function obtainPaymentMethod(Order $order): PaymentMethod {
 2     $selectedPaymentMethod = $order->getSelectedPaymentMethod();
 3     if ($selectedPaymentMethod !== null) {
 4         return $selectedPaymentMethod;
 5     }
 6     
 7     $logger = Logger::getInstance();
 8     $logger->debug("Medio de pago desconocido");
 9     
10     obtainDefaultPaymentMethod($order);
11 }
12 
13 function obtainDefaultPaymentMethod(Order $order): PaymentMethod {
14      if ($order->getDestinationCountry() == Country::FRANCE && $order->\
15 id() < 745) {
16         return PaymentTypes::PAYPAL;
17      }
18     
19     return new DefaultPaymentMethod();
20 }

Resumen del capítulo

Las expresiones y estructuras condicionales pueden hacer que seguir el flujo de un código sea especialmente difícil, particularmente cuando están anidadas o son muy complejas. Mediante técnicas de extracción podemos simplificarlas, aplanarlas y hacerlas más expresivas.

Capítulo 4. Deja atrás lo primitivo

En el que se habla de que si estamos siguiendo un paradigma orientado a objetos, todo debería ser un objeto. Sí, todo.

Todos los lenguajes de programación vienen de serie con un conjunto de tipos de datos básicos que denominamos primitivos (y en algún caso escalares, cuando no son objetos): boolean, int, float, string…, que utilizamos para representar cosas y operar con ellas. La parte mala es que son tipos genéricos y, a veces, necesitaríamos algo con más significado.

Lo ideal sería poder crear nuestros propios tipos, aptos para el dominio en el que estemos trabajando e incluyendo sus propias restricciones y propiedades. Además, podrían encapsular las operaciones que les sean necesarias. ¿Te suena el concepto? Estamos hablando de value objects.

Los value objects son objetos que representan algún concepto importante en el dominio. Ya hemos hablado un montón de veces de ellos en el blog, por lo que simplemente haré un resumen. Puedes encontrar más detalles y ejemplos en este artículo de Dani Tomé.

En resumen, los value objects:

• Representan conceptos importantes o interesantes del dominio, entendido como el dominio de conocimiento que toca el código que estamos implementando o estudiando.
• Siempre son creados consistentes, de modo que si obtienes una instancia puedes tener la seguridad de que es válida. De otro modo, no se crean y se lanza una excepción.
• Los objetos nos interesan por su valor, no por su identidad, por lo que tienen que tener alguna forma de chequear esa igualdad.
• Son inmutables, o sea, su valor no puede cambiar durante su ciclo de vida. En caso de que tengan métodos mutators, estos devolverán una nueva instancia de la clase con el valor modificado.
• Encapsulan comportamientos. Los buenos value objects atraen y encapsulan comportamientos que pueden ser utilizados por el resto del código.

Los value objects pueden ser genéricos y reutilizables, como Money, o muy específicos de un dominio.

Una aclaración que me gustaría hacer es value object es uno de los bloques de construcción en Domain Driven Design, pero el patrón de encapsular valores primitivos en objetos lo podemos (y debemos) aplicar a

Refactorizar a value objects

Refactorizar a value objects puede ser una tarea de bastante calado, ya que implica crear nuevas clases y utilizarlas en diversos puntos del código. Ahora bien, este proceso puede hacerse de forma bastante gradual. Ten en cuenta que:

• Los value objects no tienen dependencias, para crearlos solo necesitas tipos escalares o bien otros value objects.
• Los value objects se pueden instanciar allí donde los necesites, son newables.
• Normalmente, tendrás métodos para convertir los value objects a escalares, de modo que puedas utilizar sus valores con código que no puedes modificar.

Los value objects aportan varias ventajas:

• Al encapsular su validación tendrás objetos con valores adecuados que puedes usar libremente sin necesidad de validar constantemente.
• Aportarán significado a tu código, siempre sabrás cuando una variable es un precio, un email, una edad, lo que necesites.
• Te permiten abstraerte de cuestiones como formato, precisión, etc.

Propiedades múltiples para un solo concepto

Veamos un objeto típico de cualquier negocio: Customer que da lugar a varios ejemplos clásicos de value object. Un cliente siempre suele tener un nombre, que acostumbra a ser una combinación de nombre de pila y uno o más apellidos. También tiene una dirección, que es una combinación de unos cuantos datos.

 1 class Customer
 2 {
 3     private $id;
 4     private $name;
 5     private $firstSurname;
 6     private $lastSurname;
 7     private $street;
 8     private $streetNumber;
 9     private $floor;
10     private $postalCode;
11     private $city;
12 }

El constructor de nuestro Customer podría ser muy complicado, y eso que no hemos incluido todos los campos:

 1 class Customer
 2 {
 3     private $id;
 4     private $name;
 5     private $firstSurname;
 6     private $lastSurname;
 7     private $street;
 8     private $streetNumber;
 9     private $floor;
10     private $postalCode;
11     private $city;
12 
13     public function __construct(
14         string $id,
15         string $name,
16         string $firstSurname,
17         ?string $lastSurname,
18         string $street,
19         string $streetNumber,
20         string $floor,
21         string $postalCode,
22         string $city
23     )
24     {
25         $this->id = $id;
26         $this->name = $name;
27         $this->firstSurname = $firstSurname;
28         $this->lastSurname = $lastSurname;
29         $this->street = $street;
30         $this->streetNumber = $streetNumber;
31         $this->floor = $floor;
32         $this->postalCode = $postalCode;
33         $this->city = $city;
34     }
35 
36     public function fullName(): string 
37     {
38         $fullName = $this->name . ' ' . $this->firstSurname;
39         
40         if ($this->lastSurname) {
41             $fullName .= ' ' . $this->lastSurname;
42         }
43         
44         return $fullName;
45     }
46 
47     public function address(): string 
48     {
49         $address = $this->street . ', ' . $this->streetNumber;
50         
51         if ($this->floor) {
52             $address .= ' '. $this->floor;
53         }
54         
55         $address .= $this->postalCode. '-'.$this->city;
56         
57         return $address;
58     }
59 }

Solemos decir que las cosas que cambian juntas deben ir juntas, pero eso también implica que las cosas que no cambian juntas deberían estar separadas. En el constructor van todos los detalles mezclados y se hace muy difícil de manejar.

Yo no sé a ti pero a mí esto me pide un builder:

 1 class CustomerBuilder
 2 {
 3     private $name;
 4     private $firstSurname;
 5     private $lastSurname;
 6     private $street;
 7     private $streetNumber;
 8     private $floor;
 9     private $postalCode;
10     private $city;
11 
12     public function withName(string $name, string $firstSurname, ?strin\
13 g $lastSurname) : self
14     {
15         $this->name = $name;
16         $this->firstSurname = $firstSurname;
17         $this->lastSurname = $lastSurname;
18         
19         return $this;
20     }
21 
22     public function withAddress(string $street, string $streetNumber, s\
23 tring $floor, string $postalCode, string $city): self
24     {
25         $this->street = $street;
26         $this->streetNumber = $streetNumber;
27         $this->floor = $floor;
28         $this->postalCode = $postalCode;
29         $this->city = $city;
30         
31         return $this;
32     }
33 
34     public function build() : Customer
35     {
36         return new Customer(
37             $this->id,
38             $this->name,
39             $this->firstSurname,
40             $this->lastSurname,
41             $this->street,
42             $this->streetNumber,
43             $this->floor,
44             $this->postalCode,
45             $this->city
46         );
47     }
48 }

Builder que podríamos usar así:

1 $customerBuilder = new CustomerBuilder();
2 
3 $customer = $customerBuilder
4     ->withName('Fran', 'Iglesias', 'Gómez')
5     ->withAddress('Piruleta St', '123', '4', '08030', 'Barcelona')
6     ->build();

Gracias a usar el builder podemos ver que hay, al menos, dos conceptos: el nombre del cliente y su dirección. De hecho, en la dirección tendríamos también dos conceptos: la localidad y las señas dentro de esa localidad.

Vamos por partes:

Value object simple

Parece que no, pero manejamos mucha lógica en algo tan simple como un nombre. Veamos por ejemplo:

• En España usamos nombres con dos apellidos, pero en muchos otros países se suele usar un nombre con un único apellido.
• A veces necesitamos usar partes del nombre por separado, como sería el nombre de pila (“Estimada Susana”, “Sr. Pérez”). Otras veces queremos combinarlo de diferentes formas, como podría ser poner el apellido primero, lo que es útil para listados.
• Y, ¿qué pasa si queremos introducir nueva información relacionada con el nombre? Por ejemplo, el tratamiento (Sr./Sra., Estimado/Estimada, etc.).

El nombre del cliente se puede convertir fácilmente a un value object, lo que retirará cualquier lógica de la “gestión” del nombre de la clase Customer, contribuyendo al Single Responsibility Principle y proporcionándonos un comportamiento reutilizable.

Así que podemos crear un value object sencillo:

 1 class PersonName
 2 {
 3     /** @var string */
 4     private $name;
 5     /** @var string */
 6     private $firstSurname;
 7     /** @var string */
 8     private $lastSurname;
 9 
10     public function __construct(string $name, string $firstSurname, str\
11 ing $lastSurname)
12     {
13         $this->name = $name;
14         $this->firstSurname = $firstSurname;
15         $this->lastSurname = $lastSurname;
16     }
17 }

La validación debe hacerse en el constructor, de modo que solo se puedan instanciar PersonName correctos. Supongamos que nuestras reglas son:

• Name y FirstSurname son obligatorios y no pueden ser un string vacío.
• LastSurname es opcional.

Al incluir la validación tendremos el siguiente código:

 1 class PersonName
 2 {
 3     /** @var string */
 4     private $name;
 5     /** @var string */
 6     private $firstSurname;
 7     /** @var string */
 8     private $lastSurname;
 9 
10     public function __construct(string $name, string $firstSurname, ?st\
11 ring $lastSurname = null)
12     {
13         if ($name === '' || $firstSurname === '') {
14             throw new InvalidArgumentException('Name and First Surname \
15 are mandatory');
16         }
17         $this->name = $name;
18         $this->firstSurname = $firstSurname;
19         $this->lastSurname = $lastSurname;
20     }
21 }

Más adelante volveremos sobre este objeto. Ahora vamos a definir varios value objects. De momento, solo me voy a concentrar en los constructores, sin añadir ningún comportamiento, ni siquiera el método equals ya que quiere centrarme en cómo movernos de usar escalares a estos objetos.

value object Compuesto

Para crear el VO Address haremos algo parecido y crearemos una clase Address para representar las direcciones de los clientes.

Sin embargo, hemos dicho que podríamos crear un value object en torno al concepto de localidad o código postal, que incluiría el código postal y la ciudad. Obviamente, esto dependerá de nuestro dominio. En algunos casos no nos hará falta esa granularidad porque simplemente queremos disponer de una dirección postal de nuestros clientes para enviar comunicaciones. Pero en otros casos puede ocurrir que nuestro negocio tenga aspectos que dependan de ese concepto, como un servicio cuya tarifa sea función de la ubicación.

 1 class Locality
 2 {
 3     /** @var string */
 4     private $postalCode;
 5     /** @var string */
 6     private $locality;
 7 
 8     public function __construct(string $postalCode, string $locality)
 9     {
10         $this->isValidPostalCode($postalCode);
11         $this->isValidLocality($locality);
12         
13         $this->postalCode = $postalCode;
14         $this->locality = $locality;
15     }
16 
17     private function isValidPostalCode(string $postalCode) : void
18     {
19         if (\strlen($postalCode) !== 5 || (int) substr($postalCode, 0, \
20 2) > 52) {
21             throw new InvalidArgumentException('Invalid Postal Code');
22         }
23     }
24     
25     private function isValidLocality(string $locality) : void
26     {
27         if ($locality === '') {
28             throw new InvalidArgumentException('Locality should have a \
29 value');
30         }
31     }

La verdad es que podríamos hilar más fino y declarar un VO PostalCode:

 1 class PostalCode
 2 {
 3     /** @var string */
 4     private $postalCode;
 5 
 6     public function __construct(string $postalCode)
 7     {
 8         $this->isValidPostalCode($postalCode);
 9 
10         $this->postalCode = $postalCode;
11     }
12 
13     private function isValidPostalCode(string $postalCode) : void
14     {
15         if (\strlen($postalCode) !== 5 || (int) substr($postalCode, 0, \
16 2) > 52) {
17             throw new InvalidArgumentException('Invalid Postal Code');
18         }
19     }
20 }

De modo que Locality quedaría así:

 1 class Locality
 2 {
 3     /** @var PostalCode */
 4     private $postalCode;
 5     /** @var string */
 6     private $locality;
 7 
 8     public function __construct(PostalCode $postalCode, string $localit\
 9 y)
10     {
11         $this->isValidLocality($locality);
12 
13         $this->postalCode = $postalCode;
14         $this->locality = $locality;
15     }
16     
17     private function isValidLocality(string $locality) : void
18     {
19         if ($locality === '') {
20             throw new InvalidArgumentException('Locality should have a \
21 value');
22         }
23     }
24 }

En este caso, no consideramos que PostalCode sea una dependencia de Locality. Estamos hablando de tipos de datos por lo que estos objetos son newables, que es una forma de decir que se instancian a medida que se necesitan.

En fin. Volviendo a nuestro problema original de crear un objeto Address podríamos adoptar este enfoque:

 1 class Address
 2 {
 3     /** @var string */
 4     private $street;
 5     /** @var string */
 6     private $streetNumber;
 7     /** @var string */
 8     private $floor;
 9     /** @var Locality */
10     private $locality;
11 
12     public function __construct(string $street, string $streetNumber, ?\
13 string $floor, Locality $locality)
14     {
15         if ('' === $street || '' === $streetNumber) {
16             throw new InvalidArgumentException('Address should include \
17 street and number');   
18         } 
19         $this->street = $street;
20         $this->streetNumber = $streetNumber;
21         $this->floor = $floor;
22         $this->locality = $locality;
23     }
24 }

Puesto que Locality es un VO no es necesario validarla. Además, aquí no necesitamos saber cómo se construye por lo que nos daría igual si hemos optado por un diseño u otro de la clase, ya que la vamos a recibir construida y Address puede confiar en que funcionará como es debido.

Siempre que un objeto requiere muchos parámetros en su construcción puede ser interesante plantearse si tenemos buenas razones para organizarlos en forma de value objects, aplicando el principio de co-variación: si cambian juntos, deberían ir juntos. En este caso, $street, $streetNumber y $floor pueden ir juntos, en forma de StreetAddress porque entre los tres componen un concepto útil.

 1 class StreetAddress
 2 {
 3     /** @var string */
 4     private $street;
 5     /** @var string */
 6     private $streetNumber;
 7     /** @var string */
 8     private $floor;
 9 
10     public function __construct(string $street, string $streetNumber, ?\
11 string $floor)
12     {
13         if ('' === $street || '' === $streetNumber) {
14             throw new InvalidArgumentException('Address should include \
15 street and number');
16         }
17         $this->street = $street;
18         $this->streetNumber = $streetNumber;
19         $this->floor = $floor;
20     }
21 }

De este modo, Address se hace más simple y ni siquiera tiene que ocuparse de validar nada:

 1 class Address
 2 {
 3     /** @var StreetAddress */
 4     private $streetAddress;
 5     /** @var Locality */
 6     private $locality;
 7 
 8     public function __construct(StreetAddress $streetAddress, Locality \
 9 $locality)
10     {
11         $this->streetAddress = $streetAddress;
12         $this->locality = $locality;
13     }
14 }

En resumidas cuentas, a medida que reflexionamos sobre los conceptos del dominio podemos percibir la necesidad de trasladar esa reflexión al código de una forma más articulada y precisa. Pero como hemos señalado antes todo depende de las necesidades de nuestro dominio. Lo cierto es que, como veremos a lo largo del artículo, cuanto más articulado tengamos el dominio, vamos a tener más capacidad de maniobra y muchísima más coherencia.

Introduciendo los value objects

Volvamos a Customer. De momento, el hecho de introducir una serie de value objects no afecta para nada al código que tengamos, por lo que podríamos estar creando cada uno de los VO, haciendo commits, mezclando en master y desplegando sin afectar de ningún modo a la funcionalidad existente. Simplemente, hemos añadido clases a nuestra base de código y ahí están: esperando a ser utilizadas.

En este caso, tener a CustomerBuilder nos viene muy bien pues encapsula la compleja construcción de Customer, aislándola del resto del código. Podremos refactorizar Customer sin afectar a nadie. Empezaremos por el nombre:

 1 class Customer
 2 {
 3     private $id;
 4     /** @var PersonName */
 5     private $personName;
 6     private $street;
 7     private $streetNumber;
 8     private $floor;
 9     private $postalCode;
10     private $city;
11 
12     public function __construct(
13         string $id,
14         PersonName $personName,
15         string $street,
16         string $streetNumber,
17         string $floor,
18         string $postalCode,
19         string $city
20     ) {
21         $this->id = $id;
22         $this->personName = $personName;
23         $this->street = $street;
24         $this->streetNumber = $streetNumber;
25         $this->floor = $floor;
26         $this->postalCode = $postalCode;
27         $this->city = $city;
28     }
29 
30     public function fullName(): string
31     {
32         return $this->personName->fullName();
33     }
34 
35     public function address(): string
36     {
37         $address = $this->street . ', ' . $this->streetNumber;
38 
39         if ($this->floor) {
40             $address .= ' '. $this->floor;
41         }
42 
43         $address .= $this->postalCode. '-'.$this->city;
44 
45         return $address;
46     }
47 }

Como podemos ver, para empezar el constructor ya es más simple. Además, el método fullName puede delegarse al disponible en el objeto PersonName, que se puede ocupar cómodamente de cualquier variante o formato particular que necesitemos a lo largo de la aplicación.

 1 class PersonName
 2 {
 3     /** @var string */
 4     private $name;
 5     /** @var string */
 6     private $firstSurname;
 7     /** @var string */
 8     private $lastSurname;
 9 
10     public function __construct(string $name, string $firstSurname, ?st\
11 ring $lastSurname = null)
12     {
13         if ($name === '' || $firstSurname === '') {
14             throw new InvalidArgumentException('Name and First Surname \
15 are mandatory');
16         }
17         $this->name = $name;
18         $this->firstSurname = $firstSurname;
19         $this->lastSurname = $lastSurname;
20     }
21 
22     public function fullName(): string
23     {
24         $fullName = $this->name . ' ' . $this->firstSurname;
25         
26         if ($this->lastSurname) {
27             $fullName .= ' ' . $this->lastSurname;
28         }
29         
30         return $fullName;
31     }
32 }

Es por esto que decimos que los value objects “atraen” comportamientos, ya que cualquier cosa que las clases usuarias necesiten puede encapsularse en el propio VO. Si necesitásemos el nombre en un formato apto para listas podríamos hacer lo siguiente:

 1 class PersonName implements PersonNameInterface
 2 {
 3     /** @var string */
 4     private $name;
 5     /** @var string */
 6     private $firstSurname;
 7     /** @var string */
 8     private $lastSurname;
 9 
10     public function __construct(string $name, string $firstSurname, ?st\
11 ring $lastSurname = null)
12     {
13         if ($name === '' || $firstSurname === '') {
14             throw new InvalidArgumentException('Name and First Surname \
15 are mandatory');
16         }
17         $this->name = $name;
18         $this->firstSurname = $firstSurname;
19         $this->lastSurname = $lastSurname;
20     }
21 
22     public function fullName(): string
23     {
24         return $this->name .' ' . $this->surname();
25     }
26 
27     public function listName(): string
28     {
29         return $this->surname() . ', ' . $this->name;
30     }
31 
32     public function surname(): string
33     {
34         $surname = $this->firstSurname;
35 
36         if ($this->lastSurname) {
37             $surname .= ' ' . $this->lastSurname;
38         }
39 
40         return $surname;
41     }
42 
43     public function treatment() : string
44     {
45         return $this->name();
46     }
47 }

Como tenemos un Builder que encapsula la construcción de Customer, lo que hacemos es modificar esa construcción de acuerdo al nuevo diseño:

 1 class CustomerBuilder
 2 {
 3     private $personName;
 4     private $street;
 5     private $streetNumber;
 6     private $floor;
 7     private $postalCode;
 8     private $city;
 9 
10     public function withName(string $name, string $firstSurname, ?strin\
11 g $lastSurname) : self
12     {
13         $this->personName = new PersonName($name, $firstSurname, $lastS\
14 urname);
15         
16         return $this;
17     }
18 
19     public function withAddress(string $street, string $streetNumber, s\
20 tring $floor, string $postalCode, string $city): self
21     {
22         $this->street = $street;
23         $this->streetNumber = $streetNumber;
24         $this->floor = $floor;
25         $this->postalCode = $postalCode;
26         $this->city = $city;
27         
28         return $this;
29     }
30 
31     public function build() : Customer
32     {
33         return new Customer(
34             $this->id,
35             $this->personName,
36             $this->street,
37             $this->streetNumber,
38             $this->floor,
39             $this->postalCode,
40             $this->city
41         );
42     }
43 }

Fíjate que he dejado el método withName tal y como estaba. De esta forma, no cambio la interfaz pública de CustomerBuilder, como tampoco cambia la de Customer salvo en el constructor, y el código que lo usa no se enterará del cambio. En otras palabras, el ejemplo anterior funcionará exactamente igual:

1 $customerBuilder = new CustomerBuilder();
2 
3 $customer = $customerBuilder
4     ->withName('Fran', 'Iglesias', 'Gómez')
5     ->withAddress('Piruleta St', '123', '4', '08030', 'Barcelona')
6     ->build();

Por supuesto, haríamos lo mismo con el VO Address. Así queda Customer:

 1 class Customer
 2 {
 3     private $id;
 4     /** @var PersonName */
 5     private $personName;
 6     /** @var Address */
 7     private $address;
 8 
 9     public function __construct(
10         string $id,
11         PersonName $personName,
12         Address $address
13     ) {
14         $this->id = $id;
15         $this->personName = $personName;
16         $this->address = $address;
17     }
18 
19     public function fullName(): string
20     {
21         return $this->personName->fullName();
22     }
23 
24     public function address(): string
25     {
26         return $this->address->full();
27     }
28 }

El método full en Address lo resuelvo mediante un type casting a string de sus componentes, que es una manera sencilla de disponer de su valor en un formato escalar estándar:

 1 class Address
 2 {
 3     /** @var StreetAddress */
 4     private $streetAddress;
 5     /** @var Locality */
 6     private $locality;
 7 
 8     public function __construct(StreetAddress $streetAddress, Locality \
 9 $locality)
10     {
11         $this->streetAddress = $streetAddress;
12         $this->locality = $locality;
13     }
14 
15     public function full(): string
16     {
17         return (string)$this->streetAddress . ' ' . (string)$this->loca\
18 lity();
19     }
20 }

En este caso necesitaremos:

 1 class StreetAddress
 2 {
 3     /** @var string */
 4     private $street;
 5     /** @var string */
 6     private $streetNumber;
 7     /** @var string */
 8     private $floor;
 9 
10     public function __construct(string $street, string $streetNumber, ?\
11 string $floor)
12     {
13         if ('' === $street || '' === $streetNumber) {
14             throw new InvalidArgumentException('Address should include \
15 street and number');
16         }
17         $this->street = $street;
18         $this->streetNumber = $streetNumber;
19         $this->floor = $floor;
20     }
21 
22     public function __toString(): string 
23     {
24         $fullAddress = $this->street . ' ' . $this->streetNumber;
25         
26         if ($this->floor) {
27             $fullAddress .= ', '. $this->floor;
28         }
29         
30         return $fullAddress;
31     }
32 }

Y también:

 1 class PostalCode
 2 {
 3     /** @var string */
 4     private $postalCode;
 5 
 6     public function __construct(string $postalCode)
 7     {
 8         $this->isValidPostalCode($postalCode);
 9 
10         $this->postalCode = $postalCode;
11     }
12 
13     private function isValidPostalCode(string $postalCode) : void
14     {
15         if (\strlen($postalCode) !== 5 || (int) substr($postalCode, 0, \
16 2) > 52) {
17             throw new InvalidArgumentException('Invalid Postal Code');
18         }
19     }
20 
21     public function __toString(): string 
22     {
23         return $this->postalCode;
24     }
25 }