Intellij IDEA junto con el resto de "sabores" del mismo como es PHPStorm, PyCharm, WebStorm es considerado por muchos el mejor entorno de desarrollo integrado que existe en la actualidad.

Esta entrada forma parte de una serie en la que vamos a aprender a usar este editor de forma profesional, a través del conocimiento de los diferentes atajos de teclado disponibles, así como de otras funcionalidades muy útiles para el día a día.

En esta entrada vamos a centrarnos en una de las características más potentes del IDE la refactorización.

Recomendaciones previas

No es necesario que te aprendas todos el primer día. Te recomendamos elegir dos o tres atajos de teclado. Los que te parezcan más útiles y los apuntes en un posit junto a la pantalla para que no se te olviden. Practica con ellos durante algunos días y una vez que los tengas dominados, continúes tu aprendizaje con otro grupo de dos o tres.

El primer atajo de teclado que vamos a recomendarte en cada una de las entradas, es encontrar una acción.

Encontrar una acción

ALT + SHIFT + A

Con este atajo podemos lanzar el menú de selección de acción. Este atajo es de los más útiles ya que te muestra el atajo de la acción que estás buscando por lo que puedes utilizarlo cuando no te acuerdes del atajo que quieres lanzar de forma que vas a poder aprenderlos poco a poco.

Refactorización con Intellij IDEA

Renombrar variable, función, método o clase

SHIFT + F6

Con este atajo podemos renombrar una variable, una función o método o una clase. El entorno de desarrollo buscará todas las apariciones de dicho elemento y los actualizará. Si se trata de una clase cambiará el nombre del fichero que lo contiene.

Extraer constante

CTRL + ALT + C

Con este atajo podemos extraer un valor a una constante de la clase.

Extraer propiedad

CTRL + ALT + F

Con este atajo podemos extraer un valor a una propiedad de la clase.

Extraer variable

CTRL + ALT + V

Con este atajo podemos extraer un valor a una variable del método.

Extraer parametro

CTRL + ALT + P

Con este atajo podemos extraer un valor a un parámetro del método.

Extraer método

CTRL + ALT + M

Con este atajo podemos extraer un bloque de código a un método de la clase. El entorno de desarrollo buscará coincidencias del mismo fragmento de código y nos ofrecerá reemplazarlas por el nuevo método.

Cambiar la firma de un método

CTRL + F6

Con este atajo podemos cambiar la firma de un método. El entorno de desarrollo buscará todas las llamadas a ese método y actualizará el código con la nueva firma.

Mover una clase

F6

Este atajo nos va a permitir mover una clase a otro directorio. El entorno de desarrollo actualizará el namespace y buscará todas las referencias y las actualizará también.

En esta entrada vamos a centrarnos en como navegar de la forma más productiva posible es decir llegar en el menor tiempo posible al lugar al que queremos llegar, tanto si es a otro fichero como si es a una zona diferente del fichero en el que nos encontramos.

Recomendaciones previas

No es necesario que te aprendas todos el primer día. Te recomendamos elegir dos o tres atajos de teclado. Los que te parezcan más útiles y los apuntes en un posit junto a la pantalla para que no se te olviden. Practica con ellos durante algunos días y una vez que los tengas dominados, continúes tu aprendizaje con otro grupo de dos o tres.

El primer atajo de teclado que vamos a recomendarte en cada una de las entradas, es encontrar una acción.

Encontrar una acción

ALT + SHIFT + A

Con este atajo podemos lanzar el menú de selección de acción. Este atajo es de los más útiles ya que te muestra el atajo de la acción que estás buscando por lo que puedes utilizarlo cuando no te acuerdes del atajo que quieres lanzar de forma que vas a poder aprenderlos poco a poco.

Navegación entre ficheros

En el primer bloque vamos a aprender como desplazarnos entre diferentes ficheros para llegar lo antes posible al documento que queremos llegar.

Buscar la clase o archivo

CTRL + N / CTRL + SHIFT + N

Con este atajo podemos buscar la clase o el archivo al que queremos ir respectivamente. El buscador de archivos funciona incluso si el editor está indexando el proyecto.

Navegar a la referencia

CTRL + B / CTRL + CLICK

Con este atajo podemos navegar hacia la definición de una clase o método. Si existen varias disponibles, nos mostrará todas las opciones. Si tienes instalado y configurado el plugin de symfony te permite navegar entre rutas o definiciones de plantillas.

Navegar a hacia delante o hacia atrás

ALT + SHIFT + LEFT / ALT + SHIFT + RIGHT

Con este atajo podemos navegar hacia delante o hacia atrás en la navegación que hemos realizado.

Ver ficheros visitados recientemente

CTRL + E

Con este atajo podemos navegar entre los ficheros que hemos visitado recientemente.

Ver localizaciones visitadas recientemente

CTRL + SHIFT + E

Con este atajo podemos navegar entre los bloques de código que hemos visitado recientemente.

Navegación dentro de un fichero

A continuación vamos a ver los atajos que consideramos más interesantes y que nos van a permitir navegar dentro de un mismo fichero muy rápidamente y sin utilizar el ratón.

Ver estructura

CTRL + F12

Con este atajo nos abre la vista de estructura para poder navegar fácilmente entre los diferentes métodos de una clase.

Método anterior o siguiente

ALT + UP / ALT + DOWN

Con este atajo podemos desplazarnos entre los diferentes métodos de la clase.

Ir al siguiente error

F2

Con este atajo podemos desplazarnos al siguiente error dentro de un fichero.

Saltar a la línea

CTRL + G

Con este atajo podemos desplazarnos directamente a la línea a la que nos queremos mover.

Te recomendamos que leas todos los atajos disponibles tanto en la web de jetbrains como en la configuración de atajos de teclado de tu editor para que descubras por tí mismo todos los atajos disponibles.

Si te gustaría recibir una entrada como esta cada semana en tu bandeja de entrada: apúntate a nuestra academia.

Elige tu estilo

En mi opinión no tan importante que reglas utilices para organizar tus clases. Lo que sí es muy importante, es que elijas unas y te comprometas con ellas. También es muy importante que no seas dogmático y que estés dispuesto a añadir o modificar tus reglas si es que aparecen otras mejores.

No hay nada más frustrante que tratar de explicar a un desarrollador una forma mejor de hacer las cosas, y que no sea capaz de salir de sus trece, pero que tampoco sea capaz de argumentar un motivo.

Dentro de las reglas que elijas ten en cuenta que nada debe quedar al azar, si no que se note que todo está de una forma determinada por un motivo determinado y no simplemente por que ha quedado así.

Nuestro estilo

Nosotros utilizamos la guia de estilo oficial para symfony ya que es el framework con el que trabajamos. Además es muy sencillo configurar el editor para que las aplique automáticamente.

A continuación vamos a explicar el resto de reglas que utilizamos nosotros y que no son exactamente iguales a las que describe el autor en el libro. Pero que vamos a argumentarte los motivos que hemos tenido en cuenta para elegirlas.

Para ello vamos a analizar la clase Rectangle que ya conocemos de entradas anteriores.

Casi todo lo que vamos a ver son esos pequeños detalles que forman parte de nuestra política de no dejar nada al azar, y que probablemente no supongan una gran diferencia por sí sólos, pero que en conjunto y adoptadas por todo el equipo, nos permiten generar una base de código de calidad en todos nuestros proyectos.

Vamos a describir las reglas leyendo la clase de arriba a abajo.

Cabecera

La cabecera es normalmente un fragmento de código comentado que se pone encima de cada fichero. Debería indicar a que proyecto pertenece, que tipo de licencia aplica y que personas han intervenido en ella.

Lo más habitual es utilizar alguna herramienta para asegurar que todos los ficheros tienen la cabecera correcta y esta está actualizada a la última versión.

/*
 * This file is part of the clean code example package.
 *
 * Copyright (c) 2016-2020 Devtia Soluciones.
 * All rights reserved.
 *
 * @author Daniel González <daniel@devtia.com>
 */
final class Rectangle
{
    //..
}

La definición de la clase

Nosotros intentamos por defecto ser lo más restrictivos posible, y luego ir abriendo la visibilidad según sea necesario. Por eso siempre declaramos nuestras clases por defecto como final. Una palabra reservada que nos permite indicar que la clase no puede extenderse.

Las constantes de clase

Nosotros habitualmente separamos las constantes en clases independientes. Por ejemplo, si quisiéramos poner los colores como constantes, es mejor crear una clase diferente para contenerlos. De esta forma mejoramos la semántica del dominio.

final class Color
{
    const WHITE = 'FFFFFF';
    const BLACK = '000000';
}

Atributos

Como norma general declaramos todos atributos como private. Si fuera necesario cuando realizamos un diseño, algunos de estos los declaramos como protected y evitamos siempre los atributos public salvo cuando se trata de DTOs.

Si tenemos atributos de diferente visibilidad dentro de una clase los agrupamos según su visibilidad.

Dentro de cada grupo, ordenamos los atributos por orden de importancia. Los más importantes arriba. También tratamos de agruparlos por tipo, para que estén todas las fechas juntas, todos las colecciones juntas, ...

final class Rectangle
{
    /* @var Point */
    private $topLeft;

    /** @var Color */
    private $backgroundColor;

    /** @var Color */
    private $borderColor;

    /* @var float */
    private $border;

    /* @var float */
    private $height;

    /* @var float */
    private $width;

    //..
}

El constructor y el resto métodos mágicos

A continuación de los atributos escribimos el constructor de la clase. Una clase no debería encontrarse en una situación inconsistente. Por eso el constructor debería recibir todo aquello que la clase necesita para existir. De esta forma evitamos por ejemplo la existencia de un Rectangle cuya altura está sin definir.

final class Rectangle
{
    //..
    public function __construct(Point $topLeft, float $height, float $width)
    {
        $this->topLeft = $topLeft;
        $this->height = $height;
        $this->width = $width;
    }
    //..
}

Los metodos mágicos son métodos que están definidos para todas las clases en php, y que son invocados cuando ocurre una circustancia concreta. Nosotros los definimos por orden alfabético después del constructor.

Los métodos públicos

Nosotros ordenamos los métodos agrupándolos por visibilidad. Arriba del todos los métodos public luego todos los protected y finalmente todos los private.

El autor nos indica que se deberían ordenar según su importancia y mantener los métodos relacionados cerca entre sí. Nosotros creemos que esto podría tener sentido en el momento de publicar el libro, pero es una regla dificil de aplicar, cuando por ejemplo un mismo método se llama desde diferentes métodos, ¿junto a cual lo pones?

Los editores modernos nos permiten navegar con facilidad entre métodos aúnque no estén cercanos entre sí, asi que nosotros simplemente los ordenamos alfabeticamente y configuramos el editor para que haga esto automáticamente por nosotros.

El resto de métodos

Los métodos que no son public deberían declararse private a menos que exista una buena razón para ello. Los ordenamos también por orden alfabético y dejamos que el editor se encarge de esta tarea.

Bloques de código

Para explicar esto es necesario traer un ejemplo un poco más complejo. Veamos un ejemplo real de uno de nuestros proyectos.

final class ProposalController extends AbstractProposalController
{
    //..
    public function copyAction(Project $proposal)
    {
        $this->throwNotFoundExceptionIfNotIsPublicProposal($proposal);

        $copyManager = $this->get('app.service.project_copy_manager');
        $publicProposal = $copyManager->generatePublicProposal(
            $proposal,
            null,
            \AppBundle\Entity\Project\Type::PUBLIC_PROPOSAL_CLIENT_VERSION
        );

        $manager = $this->get('app.service.project_manager');
        $manager->update($publicProposal);

        $this->addFlash('success', 'proposal successfully updated');

        return $this->redirectToRoute('_public.proposal.view', ['hash' => $publicProposal->getHash()]);
    }
    //..
}

Si ves el ejemplo anterior puedes ver que cada concepto está separado por un salto de línea. Lo primero que hacemos es la validación o cláusulas de guarda, de las que hablaremos en otra entrada más adelante.

Lo siguiente que hacemos es obtener una copia de la propuesta a través del servicio correspondiente. Después actualizamos esa copia, mensaje de éxito y redirección a la nueva propuesta.

Cada concepto está separado por un salto de línea facilitando su entendimiento al lector.

Ni un salto de línea de más

El último detalle. Ya hemos visto donde sí debemos poner un salto de línea. En nuestra opinión no se deben añadir saltos de línea adicionales, porque dan la sensación de estar ahí por que sí, en lugar de porque tienen que estar.

¿Pruebas automáticas?

Las pruebas o la batería de pruebas es un software que debe escribirse en paralelo a nuestro propio software y cuya responsabilidad es comprobar que nuestro software funciona correctamente. Básicamente es software que prueba nuestro software.

Puede que intuitivamente pienses que construir una batería de pruebas, es trabajo adicional, ya que probablemente tardarás más tiempo y por lo tanto tu trabajo será más caro para tus clientes pero esto no es así.

Cuando tienes una buena batería de pruebas, la primera "derivada" es que vas a cometer menos errores. Menos errores supone menos tiempo arreglando errores y más tiempo programando. Además supone menos frustración en los usuarios.

La segunda derivada es que puedes hacer cambios con mayor confianza, y esto te hace ir más rápido. Las pruebas detectarán que has roto, y simplemente tendrás que arreglarlo, un equipo con una buena batería de pruebas termina trabajando mucho más rápido que un equipo que no las tiene.

Hay una tercera derivada y es que al desarrollar tu batería de pruebas te va a permitir diseñar mejor software, pero esto es algo en lo que profundizaremos en una entrada más adelante.

¿Si es tan bonito por que no todo el mundo hace pruebas automáticas?

Cuando escribes pruebas debes ser tan cuidadoso cómo con el código de producción. Todo lo que hemos comentado ya en esta serie sobre elegir buenos nombres, funciones, argumentos, etc son cosas que también aplican a las pruebas automáticas.

Escribir buenas pruebas requiere cierta técnica y ocurre que muchos programadores o equipos comienzan haciendo pruebas, y al no ser pruebas de calidad terminan teniendo una batería de pruebas que supone más un problema que una solución. Tras esta mala experiencia desisten, por eso en esta entrada vamos a explicarte cómo escribir buenas pruebas.

Escribe tus pruebas "PRIMERO"

FIRST o PRIMERO es un acrónimo que se utiliza para describir las características que debería tener una prueba.

Fast o Rápidas

Una prueba, así como la batería de pruebas a la que pertenecen deberían ser tan rápidas cómo sea posible. ¿Cuánto? Pues depende del tipo de prueba y del proyecto. El autor no se moja en este aspecto, pero en mi opinión deberías mantener cada prueba por debajo de 1 segundo.

Independent o independientes

Unas pruebas no deberían depender de otras. Esto te permitirá ejecutar aisladamente las pruebas que fallen en lugar de tener que ejecutar toda la batería o un conjunto de pruebas.

Repeatable o repetibles

El resultado de una prueba debería ser siempre el mismo y no variar si la ejecutas varias veces. De esta forma, podrás ejecutar una prueba una y otra vez, hasta que arregles el error. De lo contrario tendrías continuamente errores que luego no vas a poder reproducir.

Self-validating o validación automática

Lo que quiere decir esta regla es que las pruebas no deberían depender de una revisión, por ejemplo que el resultado fuera un texto que luego necesitarás leer para saber si es correcto o no. La prueba debe pasar o no pasar, no debería haber otro resultado posible.

Timely o en el momento correcto

El autor introduce en este capítulo las reglas del ciclo de TDD: rojo, verde y refactorización, pero no quiero profundizar mucho sobre este aspecto aquí, porque tendremos el libro "Test Driven Development: By Example" por en este blog y en el canal de youtube más pronto que tarde.

Show me the code

Supongamos que tenemos la clase rectangulo que vimos en el capítulo de estructuras vs objetos.

class Rectangle
{
    private $height;
    private $width;

    public function __construct(float $height, float $width)
    {
        $this->height = $height;
        $this->width = $width;
    }

    public function area(): float
    {
        return round($this->height * $this->height, 2);
    }
}

Escribir una prueba es una tarea muy sencilla, normalmente es simplemente una clase que tiene que extender de algún tipo de framework de pruebas, así es como se hace con phpunit

class RectangleTest extends \PHPUnit\Framework\TestCase
{
    public function test_area()
    {
        $rectangle = new Rectangle(1.11, 2.22);
        $this->assertSame(2.46, $rectangle->area());
    }
}

Fácil, pero ¿que ocurre al ejecutarlo?

Efectivamente había un error en el código. En este caso lo hemos introducido a posta, pero es un tipo de error que se puede cometer fácilmente.

¿Has visto cual?

Veamos un ejemplo con la clase responsable de notificar a los usuarios de la academia que hay un nuevo contenido disponible. En el método send recibiremos un usuario y la entrada que debe serle notificada.

Partiremos de este primer ejemplo donde la gestión de errores ensucia el código para ver cuales son las diferentes mejoras que podemos ir realizando.

class SendCommand extends AbstractCommand
{
    private function send(User $user, Post $post): void
    {
        $code = $this->mailer->sendTemplate(
            [$user->getEmail() => $user->getName()],
            $post->getName(),
            '@App/Command/Academy/Mailing/Post/post.html.twig',
            [
                'user' => $user,
                'post' => $post,
            ]
        );

        if (Code::TIMEOUT == $code) {
            sleep(20);
            $this->send($user, $post);
        } elseif (Code::ADDITIONAL_DATA_REQUIRED == $code) {
            $this->log(
                sprintf(
                    'message [%06d] for user "%s" could not be sent because was unavailable',
                    $post->getId(),
                    $user->getEmail()
                )
            );
        } elseif (Code::ADDITIONAL_DATA_REQUIRED == $code) {
            $this->log(
                sprintf(
                    'message [%06d] for user "%s" could not be sent because additional space was needed',
                    $post->getId(),
                    $user->getEmail()
                )
            );
        } elseif (Code::INBOX_IS_FULL == $code) {
            $this->log(
                sprintf(
                    'message [%06d] for user "%s" could not be sent because the inbox was full',
                    $post->getId(),
                    $user->getEmail()
                )
            );
        }
    }
}

Como se puede ver este ejemplo inicial tiene bastante que mejorar.

Evita utilizar códigos de error

Los códigos de error son difíciles de manejar. En general van a requerir un montón de estructuras if / else para poder lidiar con los diferentes códigos de error.

Además siempre cabe la posibilidad de que se añada un nuevo código de error que nosotros no tengamos capturado. En lugar de códigos de error sería conveniente utilizar excepciones.

A continuación vemos exactamente el mismo código pero utilizando excepciones:

class SendCommand extends AbstractCommand
{
    private function send(User $user, Post $post): void
    {
        try {
            $this->mailer->sendTemplate(
                [$user->getEmail() => $user->getName()],
                $post->getName(),
                '@App/Command/Academy/Mailing/Post/post.html.twig',
                [
                    'user' => $user,
                    'post' => $post,
                ]
            );
        } catch (TimeoutException $e) {
            sleep(20);
            $this->send($user, $post);
        } catch (AdditionalDataRequiredException $e) {
            $this->log(
                sprintf(
                    'message [%06d] for user "%s" could not be sent because was unavailable',
                    $post->getId(),
                    $user->getEmail()
                )
            );
        } catch (ServiceUnavailableException $e) {
            $this->log(
                sprintf(
                    'message [%06d] for user "%s" could not be sent because additional space was needed',
                    $post->getId(),
                    $user->getEmail()
                )
            );
        } catch (InboxIsFullException $e) {
            $this->log(
                sprintf(
                    'message [%06d] for user "%s" could not be sent because the inbox was full',
                    $post->getId(),
                    $user->getEmail()
                )
            );
        }
    }
}

De momento no hemos mejorado mucho y nuestro código sigue teniendo una pinta terrible, pero estamos un paso más cerca de tener nuestro código bastante más elegante.

Separar lógica y gestión de errores

Lo que vamos a hacer ahora es separar la responsabilidad en dos métodos. Uno de ellos contendrá la lógica de negocio y el otro contendrá la gestión de errores. Este sencillo cambio hace nuestro código mucho más legible y fácil de mantener.

class SendCommand extends AbstractCommand
{
    private function handleSendException(User $user, Post $post, \Exception $exception): void
    {
        try {
            throw $exception;
        } catch (TimeoutException $e) {
            // ..
        } catch (AdditionalDataRequiredException $e) {
            // ..
        } catch (ServiceUnavailableException $e) {
            // ..
        } catch (InboxIsFullException $e) {
            // ..
        }
    }

    private function send(User $user, Post $post): void
    {
        try {
            $this->mailer->sendTemplate(
                [$user->getEmail() => $user->getName()],
                $post->getName(),
                '@App/Command/Academy/Mailing/Post/post.html.twig',
                [
                    'user' => $user,
                    'post' => $post,
                ]
            );
        } catch (\Exception$exception) {
            $this->handleSendException(user, $post, $exception);
        }
    }
}

Evita los detalles de implementación

Nuestro código ha mejorado bastante, pero todavía tiene un problema. Nuestro comando conoce los detalles de implementación del sistema de envío de correo. Esto supone un problema, si en el futuro quisiéramos enviar el correo o las notificaciones con otra librería o a través de otro medio, nuestro comando dejaría de funcionar.

Para ello es conveniente evitar conocer los detalles de implementación ( las excepciones ) que contiene el sistema de envío, con lo que nos debería quedar algo así.

class SendCommand extends AbstractCommand
{
    private function handleSendException(User $user, Post $post, \Exception $exception): void
    {
        $this->log(
            sprintf(
                'message [%06d] for user "%s" with message "%s"',
                $post->getId(),
                $user->getEmail(),
                $exception->getMessage()
            )
        );
    }

    private function send(User $user, Post $post): void
    {
        try {
            $this->mailer->sendTemplate(

                [$user->getEmail() => $user->getName()],
                $post->getName(),
                '@App/Command/Academy/Mailing/Post/post.html.twig',
                [
                    'user' => $user,
                    'post' => $post,
                ]
            );
        } catch (\Exception$exception) {
            $this->handleSendException($user, $post, $exception);
        }
    }
}

Empezemos describiendo los motivos por los que no deberías hablar con extraños: muchas veces cuando tenemos una clase que a su vez está formada por objetos de otras clases y estas a su vez por otras, tenemos una estructura de clases. Hasta aquí todo bien, pero: ¿qué ocurre cuando estas estructuras se vuelven complejas? Veamos un ejemplo que podría darse en un comando de symfony.

class CustomCommand extends Command
{
    protected function execute(InputInterface $input, OutputInterface $output): int
    {
        $this->getApplication()->getKernel()->getContainer()->getCustomService()->getManager()->execute();

        return 1;
    }
}

Como puedes ver, estamos acoplando de forma innecesaria nuestro código a todas las clases que aparecen en la cadena de llamadas. Cualquier cambio en estas clases o en las relaciones entre ellas podría suponer que nuestro código dejase de funcionar. Para que esto no suceda viene al rescate la ley de demeter.

La ley de demeter

La ley de demeter fue descrita por primera vez dentro del proyecto demeter en 1987. Como curiosidad quiero contarte que Demeter, hace referencia a la diosa griega de la agricultura. Querian hacer referencia a algo así como "cultivar" software en contraposición a "construir" el software.

La ley indica que desde un método solo deberías "hablar" con aquellos a quien conozcas bien. Y estos son:

• Métodos de la misma clase.
• Métodos de los objetos de la clase.
• Métodos de los objetos creados en la misma función.
• Métodos de los objetos pasados como argumento a la función.

¿Y cómo lo soluciono?

Ya hemos detectado que es lo que no debes hacer, te voy a proponer ahora tres opciones a tener en cuenta cuando detectes este problema en tu código.

No hacer nada

La primera es no hacer nada. Es la solución más sencilla, y la peor de las tres que vamos a ver, pero como ya vimos en la entrada sobre los dogmas en el desarrollo de software, si crees que las clases que estás llamando y sus relaciones están muy consolidadas, podrías permitirte el lujo de realizar este tipo de llamadas en cadena.

Usar atajos

La segunda consiste en hacer atajos que permitan evitar estas llamadas encadenadas. Esta es una solución bastante rápida, que te puede permitir salir del paso en algún momento.

Por ejemplo en CustomService podríamos añadir el método executeManager.

class CustomService
{
    public function executeManager(): void
    {
        $this->getManager()->execute();
    }
}

Esta solución como puedes imaginarte tampoco es la mejor. Te permite abstraer parte de esa cadena de llamadas y por lo tanto es una opción mejor que al principio, ya que si la relacion cambia sólo tendrás que cambiar en este punto las llamadas.

El problema de esta solución es que puedes encontrarte con tu código con un montón de estos métodos atajos, que realmente por diseño no deberían encontraser ahí, pero están simplemente para hacer cumplir la ley de demeter.

Inyectar dependencias

La solución buena, como probablemente ya te venías imaginando es inyectar las dependencias. Veamos un ejemplo.

class CustomCommand extends Command
{
    public function setCustomManager(CustomManager $customManager)
    {
        $this->manager = $customManager;
    }

    protected function execute(InputInterface $input, OutputInterface $output): int
    {
        $this->manager->execute();
    }
}

Hemos añadido como dependencia la clase CustomManager que era la que realmente necesitamos, y se la hemos inyectado a través de un setter, pero hemos eliminado toda la cadena de dependencias y las relaciones entre sí.

Con este sencillo cambio hemos podido eliminar fácilmente todas las dependencias sobrantes.

Estructuras de datos

Una estructura de de datos, es una clase o un objeto que expone la información que contiene. En el ejemplo hemos evitado el uso de getters y setter, pero sería exactamente lo mismo si los tuviera, lo consideraremos una estructura, porque expone su información. Otras clases serán responsables de realizar las funcionalidad que necesitemos.

class Circle
{
    /** @var Point */
    public $center;
    public $radius;
}

class Geometry
{
    const PI = 3.141592653589793;

    public function area($shape): float
    {
        return $shape->radius * $shape->radius * Geometry::PI;
    }
}

Objetos

Con el mismo ejemplo si usaramos el paradigma de la orientación a objetos, debemos ocultar cuál es la información y la estructura de los datos internos, y debemos exponer la funcionalidad que queremos.

class Circle
{
    const PI = 3.141592653589793;

    /** @var Point */
    private $center;
    private $radius;

    public function area(): float
    {
        return $this->radius * $this->radius * self::PI;
    }
}

Aunque el ejemplo es muy sencillo nos permite entender la diferencia. Una estructura de datos es un elemento sencillo que solamente contiene información, mientras que la lógica se encuentra en otras clases. Un objeto es una abstracción que expone su funcionalidad.

Añadir nuevas estructuras de datos / objetos

Vamos añadir un nuevo tipo: Rectangle y vemos a ver que cambios son necesarios en cada aproximación.

class Rectangle
{
    /** @var Point */
    public $topLeft;
    public $height;
    public $width;
}

class Circle
{
    /** @var Point */
    public $center;
    public $radius;
}

class Geometry
{
    const PI = 3.141592653589793;

    public function area($shape): float
    {
        if ($shape instanceof Rectangle) {
            return $shape->height * $shape->width;
        }

        if ($shape instanceof Circle) {
            return $shape->radius * $shape->radius * Geometry::PI;
        }

        throw new InvalidArgumentException();
    }
}

class Rectangle
{
    /** @var Point */
    private $topLeft;
    private $height;
    private $width;

    public function area(): float
    {
        return $this->height * $this->width;
    }
}

class Circle
{
    const PI = 3.141592653589793;

    /** @var Point */
    private $center;
    private $radius;

    public function area(): float
    {
        return $this->radius * $this->radius * self::PI;
    }
}





    

¿Que diferencia ves entre ambos?. En la primera aproximación además de añadir la nueva estructura, hemos tenido que modificar Geometry::area(). En el ejemplo es un cambio muy sencillo, pero nos sirve para identificar que cuando añadimos nuevas estructuras vamos a tener que revisar el código que las utiliza para que sea capaz de manejar esta nueva estrucutra, lo cual nos puede llevar a añadir errores en un códiugo que ya estaba funcionando.

En cambio en la aproximación orientada a objetos no hemos tenido que modificar ni una coma del código que ya teníamos, y simplemente hemos tenido que añadir un nuevo objeto.

Añadir funcionalidad

Vamos a añadir una nueva funcionalidad, el cálculo del perímetro: perimeter a ver que tal se comporta cada una de nuestras implementaciones.

class Rectangle
{
    /** @var Point */
    public $topLeft;
    public $height;
    public $width;
}

class Circle
{
    /** @var Point */
    public $center;
    public $radius;
}

class Geometry
{
    const PI = 3.141592653589793;

    public function area($shape): float
    {
        if ($shape instanceof Rectangle) {
            return $shape->height * $shape->width;
        }

        if ($shape instanceof Circle) {
            return $shape->radius * $shape->radius * Geometry::PI;
        }

        throw new InvalidArgumentException();
    }

    public function perimeter($shape): float
    {
        if ($shape instanceof Rectangle) {
            return 2 * $shape->height + 2 * $shape->width;
        }

        if ($shape instanceof Circle) {
            return 2 * Geometry::PI * $shape->radius;
        }

         throw new InvalidArgumentException();
    }
}

class Rectangle
{
    /** @var Point */
    private $topLeft;
    private $height;
    private $width;

    public function area(): float
    {
        return $this->height * $this->width;
    }

    public function perimeter(): float
    {
        return 2 * $this->height + 2 * $this->width;
    }
}

class Circle
{
    const PI = 3.141592653589793;

    /** @var Point */
    private $center;
    private $radius;

    public function area(): float
    {
        return $this->radius * $this->radius * self::PI;
    }

    public function perimeter(): float
    {
        return 2 * self::PI * $this->radius;
    }
}








    

En este caso, nuestra primera aproximación ha sido más sencilla. No hemos tenido que tocar el código que ya teníamos funcionando y sólo hemos tenido que añadir una nueva función.

En cambio en la aproximación orientada a objetos hemos tenido que tocar cada una de las clases que teníamos para añadirles esta funcionalidad. El ejemplo es muy sencillo, pero nos sirve para identificar el problema.

Conclusiones

A nivel de líneas de código no existe una diferencia sustancial. Tampoco es razonablemente más sencillo de implementar o de mantener una u otra aproximación, pero cuando utilizamos estructuras, tendremos cierta facilidad cuando queramos añadir nueva funcionalidad, mientras que cuando utilizamos objetos tendremos facilidades para añadir nuevos tipos.

Número de argumentos

Según el autor podríamos clasificar las funciones o los métodos según el número de argumentos posibles.

Monádicaos tienen un sólo argumento, son fáciles de testear y fáciles de entender. No hay lugar a dudas en cuanto a que es lo que hace y probablemente será bastante sencillo crear un test unitario para la misma. Siempre que podamos debemos basar nuestra api en este tipo de funciones.

Diádicos tienen dos argumentos. Siguen siendo relativamente fáciles de entender, y probablemente seguirán siendo fáciles de testear.

Triadicos son las que tienen tres argumentos, comienza a complicarse la forma de testear, aumenta la complejidad ciclomática o número de "caminos" posibles dentro de la función, y se complica recordar los argumentos y su orden. Este tipo de funciones deberían evitarse si es posible.

Cuatro o más argumentos Este tipo de funciones tienen todos los problemas que ya hemos comentado pero en mayor expotente. Veamos un ejemplo a continuación la función que ejecuta el filtro localizeddate de twig.

function twig_localized_date_filter(
    Twig_Environment $env,
    $date,
    $dateFormat = 'medium',
    $timeFormat = 'medium',
    $locale = null,
    $timezone = null,
    $format = null,
    $calendar = 'gregorian'
) {
    //..
}

Habitualmente usamos esta función de esta forma lo que la hace muy cómoda de usar

{{ item.date|localizeddate }}
{{ item.date|localizeddate('short', 'none') }} {# el uso de las constantes es muy cómodo en el día a día. #}

El problema viene cuando queremos pasarle un formato personalizado. Es muy dificil de recordar cuales son los argumentos, y tenemos que ir a la documentación para comprobarlo. Además los primeros dos argumentos son ignorados lo que la vuelve un poco confusa.

{{ item.date|localizeddate('none', 'none', null, null, 'MMMM y') }}
{{ item.date|localizeddate('full', 'full', null, null, 'MMMM y') }} {# ambas hacen lo mismo. #}

¿Que os parece si cambiamos esta función por dos? En la primera usaremos las constantes definidas para $dateFormat y $timeFormat mientras que en la segunda usaremos un formato personalizado.

function twig_localized_date_filter(
    Twig_Environment $env,
    $date,
    $dateFormat = 'medium',
    $timeFormat = 'medium',
    $locale = null,
    $timezone = null,
    $calendar = 'gregorian'
) {
//..
}

function twig_localized_date_filter_by_format(
    Twig_Environment $env,
    $date,
    $customFormat = null,
    $locale = null,
    $timezone = null,
    $calendar = 'gregorian'
) {
//..
}

Hemos reducido un poco el número de argumentos y hemos facilitado su utilización, ya que el uso de la segunda función quedaría en algo parecido a esto.

Nota: Aunque todavía son muchos argumentos el primero es injectado por twig asi que contaría uno menos.

{{ item.date|localizeddate('da_igual_lo_que_pongas', 'da_igual_lo_que_pongas', null, null, 'MMMM y') }} {# antes #}
  {{ item.date|localizeddate_by_format('MMMM y') }} {# mejor esta no? #}

Grupos de argumentos

En el caso en el que tenemos una función con un grupo de argumentos relacionados entre sí, podemos agruparlos todos ellos en una clase de forma que nuestro código mejora en su legibilidad. Es lo que han hecho aquí.

¿Que os parece si crearamos una clase para almacenar la configuración de la localización $locale, $timezone, $calendar. Es muy probable que este grupo de argumentos se repitan en otras funciones.

class Localization
{
    private $locale = null;
    private $timezone = null;
    private $calendar = 'gregorian';

    public function __construct($locale, $timezone, string $calendar)
    {
        $this->locale = $locale;
        $this->timezone = $timezone;
        $this->calendar = $calendar;
    }

}

Con esto mejoramos mucho la legibilidad del código, veamos cómo quedarían nuestras funciones anteriores

function twig_localized_date_filter(
    Twig_Environment $env,
    $date,
    $dateFormat = 'medium',
    $timeFormat = 'medium',
    $localization
) {
//..
}

function twig_localized_date_filter_by_format(
    Twig_Environment $env,
    $date,
    $customFormat = null,
    $localization
) {
//..
}

Orden de argumentos

A partir de este punto todo lo que vamos a ver no aparece en el libro, pero si que hemos querido completarlo con algunos criterios adicionales. Deberías tener en cuenta las siguientes condiciones a la hora de elegir el orden de los argumentos.

• Los más importantes primero.
• Utiliza el contexto para que el lector sepa cual es el primer argumento.
• Trata de agrupar por tipos.
• Argumentos opcionales al final.

Nombres

Los nombres de tus argumentos son parte de tu función. Trata de que séan lo más expecíficos posibles, ayuda al lector a entender tu función y lo que pueda esperar de ella, a través de esos nombres. ¿Que te parece este cambio?

function twig_localized_date_filter(
    Twig_Environment $env,
    $dateTime, // $date no era fiel a la realidad, ya que en ese argumento no importa sólo la fecha, si no también la hora.
    $dateFormat = 'medium',
    $timeFormat = 'medium',
    $localization
) {
//..
}

Tipado

El último apartado que me gustaría ver en esta entrada es el tipado. La regla es muy sencilla. Tipa siempre que puedas.

function twig_localized_date_filter(
    Twig_Environment $env,
    \DateTime $date,
    string $dateFormat = 'medium',
    string $timeFormat = 'medium',
    Localization $localization = null
) {
//..
}

function twig_localized_date_filter_by_format(
    Twig_Environment $env,
    \DateTime $date,
    string $customFormat,
    Localization $localization = null
) {
//..
}

El tipado también forma parte de tu función, quizá no tengas claro que es exactamente $localization, pero el tipado te ayuda a entender que se trata de una clase.

Hacer una única cosa

Una función solo debería hacer una única cosa, y además debería de ser ser capaz de hacerla bien. Este concepto a la vez que es sencillo de entender es bastante complejo de explicar, así que vamos a definir algunas características que pueden indicarte que una de tus funciones hacen más de una cosa.

Demasiado larga

Si una función tiene demasiadas líneas de código, es muy probable que esté haciendo varias cosas a la vez. Deberías tratar de encontrar bloques dentro de esa misma función que hagan una cosa concreta e ir extrayendolas en funciones más pequeñas.

El límite exacto para considerarse demasiado larga es un poco difuso, pero por encima de 20 líneas deberías al menos plantearte si tu función es demasiado larga.

Secciones

Como continuación a lo anterior, si una función puede dividirse en secciones, nos encontramos ante un caso claro de que esa función hace más de una cosa.

A continuación vemos la función Lock::acquire

/**
 * {@inheritdoc}
 */
public function acquire(bool $blocking = false): bool
{
    try {
        if ($blocking) {
            if (!$this->store instanceof BlockingStoreInterface) {
                throw new NotSupportedException(sprintf('The store "%s" does not support blocking locks.', get_debug_type($this->store)));
            }
            $this->store->waitAndSave($this->key);
        } else {
            $this->store->save($this->key);
        }

        $this->dirty = true;
        $this->logger->info('Successfully acquired the "{resource}" lock.', ['resource' => $this->key]);

        if ($this->ttl) {
            $this->refresh();
        }

        if ($this->key->isExpired()) {
            try {
                $this->release();
            } catch (\Exception $e) {
                // swallow exception to not hide the original issue
            }
            throw new LockExpiredException(sprintf('Failed to store the "%s" lock.', $this->key));
        }

        return true;
    } catch (LockConflictedException $e) {
        $this->dirty = false;
        $this->logger->notice('Failed to acquire the "{resource}" lock. Someone else already acquired the lock.', ['resource' => $this->key]);

        if ($blocking) {
            throw $e;
        }

        return false;
    } catch (\Exception $e) {
        $this->logger->notice('Failed to acquire the "{resource}" lock.', ['resource' => $this->key, 'exception' => $e]);
        throw new LockAcquiringException(sprintf('Failed to acquire the "%s" lock.', $this->key), 0, $e);
    }
}

Podemos observar 3 secciones principales. En la primera trata de adquirir el bloqueo, en la segunda comprueba si el bloqueo debería haber expirado y en el último bloque realiza el manejo de errores. Podríamos facilitarle mucho la vida al lector si extrajeramos esos bloques dejándolos en algo similar a esto.

/**
 * {@inheritdoc}
 */
public function acquire(bool $blocking = false): bool
{
    try {
        $this->tryAcquire($blocking);
        $this->releaseIfExpired();

        return true;
    } catch (\Exception $e) {
        return $this->handleException($e);
    }
}

switch

Un bloque switch es probablemente un indicador de que una función hace varias cosas. La forma de solucionar esto es extraer ese bloque switch para que la única cosa que haga nuestra función es decidir qué hacer en función del valor que le pasemos a switch.

A continuación vemos un caso válido de un bloque switch dentro de la clase Store\StoreFactory, ya que aunque tiene un elemento switch la función hace una única cosa, en este caso devolver la instancia de Store\PersistingStoreInterface correcta en función del tipo de conexión que estemos utilizando.

/**
     * @param \Redis|\RedisArray|...
     *
     * @return PersistingStoreInterface
     */
    public static function createStore($connection)
    {
        if (!\is_string($connection) && !\is_object($connection)) {
            throw new \TypeError(sprintf('Argument 1 passed to "%s()" must be [...], "%s" given.');
        }

        switch (true) {
            case $connection instanceof \Redis:
            case $connection instanceof \RedisArray:
            case $connection instanceof \RedisCluster:
            case $connection instanceof \Predis\ClientInterface:
            case $connection instanceof RedisProxy:
            case $connection instanceof RedisClusterProxy:
                return new RedisStore($connection);
            // en total hay 32 casos diferentes.
        }

        throw new InvalidArgumentException(sprintf('Unsupported Connection: "%s".', $connection));
    }

Un sólo nivel de abstracción

Dentro de una misma función debemos mantenernos siempre dentro del mismo nivel de abstracción.

Por ejemplo si tuviéramos una capa de dominio de negocio y una capa de persistencia de datos, dentro de una misma función no deberíamos pasar de un nivel a otro, por lo cual tendríamos funciones con lógica de negocio y funciones con lógica de persistencia de datos.

Procesamiento de errores

Empezaremos indicando que el procesamiento de errores es mucho más sencillo a través de excepciones que de códigos de error, pero esto lo veremos mucho más en profundidad en el capítulo de procesamiento de errores.

El problema que tienen los bloques try / catch es que dificultan mucho la lectura.Si tenemos una función donde además de la lógica de la función tiene uno o más bloques try / catch, probablemente deberíamos extraer la parte de la lógica de negocio y dejar esa función sólamente con los bloques try catch tal y cómo hicimos con la función Lock::acquire en el ejemplo anterior.

Evita el uso de contracciones

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

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

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

Sé consistente

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

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

Utiliza el contexto

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

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

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

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

Hace lo que dice que hace

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

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

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

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

Explica cómo debe usarse

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

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

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

Conclusiones

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