En DEVTIA otorgamos una gran importancia al transcurso de las semanas previas al comienzo. En ellas se deberán realizar algunas acciones que serán determinantes. En esta fase, el éxito dependerá de ambas partes, y en gran medida del esfuerzo que sea capaz de realizar el propio cliente.

Nuestra metodología exige que nuestros clientes se impliquen, y es en esta fase donde el cliente tiene una carga de trabajo más importante, así que durante estas semanas puedes esperar que te pidamos algunas de estas tareas:

Análisis de la competencia

Un buen punto de partida para un proyecto de desarrollo de software es ver cómo han resuelto otros tus mismos problemas. No se trata de copiar a la competencia, sino de obtener las mejores ideas de cada sitio y luego evolucionarlas según corresponda. Nosotros somos expertos en el desarrollo de software pero no conocemos en profundidad tu negocio, por lo que nadie mejor que tú para hacer este análisis.

Escribir documentación

Necesitamos que pongas por escrito tus ideas. Entre otras cosas queremos saber:

1. ¿Cuál es la situación actual?
2. ¿Cuáles son los objetivos del proyecto?
3. ¿Qué niveles de acceso son necesarios?
4. ¿Cuáles son las principales funcionalidades?

Recopilar datos

Necesitamos que nos facilites los datos iniciales que quieres que tenga tu proyecto. Por ejemplo, si partimos de una aplicación anterior, puedes ir trabajando con la base de datos previa para tener listos los datos para la nueva aplicación.

Resolver dudas

Según vayamos teniendo más información del alcance probablemente vamos a exponerte dudas, así como sugerencias e ideas.

Sesiones

Independientemente de todo el trabajo anterior vamos a tener una o más sesiones de puesta en común, ya que nosotros creemos firmemente en la comunicación directa.

En estas sesiones repasaremos contigo el trabajo que has realizado, así como te expondremos el trabajo que hemos desarrollado nosotros. En equipo tomaremos las mejores decisiones para tu proyecto.

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.

¿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?

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.

bloques de código

Por regla general deberías evitar el uso de comentarios. Los comentarios pueden parecer una herramienta muy útil ya que cuando estamos desarrollando puede que nos encontremos con que queremos explicar mejor cómo funciona nuestro código o por que hemos tomado una determinada decisión.

Pero cuando usamos un comentario de código donde antes teníamos un problema: que nuestro código no era suficientemente sencillo de entender, ahora tenemos dos: nuestro código sigue sin entenderse con facilidad, y ahora además debo ocuparme de mantener los comentarios que he realizado.

Puedes pensar que mantener ese comentario no es mucho trabajo, pero que tal si esa energía qué has gastado en mantener un comentario la hubieras gastado en hacer algo más productivo. ¿mejor, no?.

Vemos un ejemplo con el TokenStorage del componente Security de Symfony.

namespace Symfony\Component\Security\Core\Authentication\Token\Storage;

use Symfony\Component\Security\Core\Authentication\Token\TokenInterface;
use Symfony\Contracts\Service\ResetInterface;

/**
 * TokenStorage contains a TokenInterface.
 */
class TokenStorage implements TokenStorageInterface, ResetInterface
{
    // ..
    public function setToken(TokenInterface $token = null)
    {
        if ($token) {
            // ensure any initializer is called
            $this->getToken();
        }

        $this->initializer = null;
        $this->token = $token;
    }
    //..
}

El autor de este código necesitaba hacer algunas llamadas antes de configurar el token. Se dio cuenta que que no era sencillo de entender y que otra persona que viniera detrás probablemente no entendería el motivo de esa llamada, asi que utilizó un comentario para aclararlo todo. ¿Pero que te parece si hubiera hecho esto?

namespace Symfony\Component\Security\Core\Authentication\Token\Storage;

use Symfony\Component\Security\Core\Authentication\Token\TokenInterface;
use Symfony\Contracts\Service\ResetInterface;

/**
 * TokenStorage contains a TokenInterface.
 */
class TokenStorage implements TokenStorageInterface, ResetInterface
{
    // ..
    public function setToken(TokenInterface $token = null)
    {
        if ($token) {
            $this->callInitializer();
        }

        $this->initializer = null;
        $this->token = $token;
    }

    private function callInitializer(): void
    {
        $this->getToken();
    }
    //..
}

Como ves hemos eliminado el comentario y hemos mantenido e incluso mejorado la expresividad, ya que el código es igual de explícito. Por lo tanto siempre que nos veamos en la necesidad de añadir comentarios, debemos plantearnos si podríamos mejorar la expresividad de nuestro código mejorando los nombres que estamos utilizando o extrayendo métodos como en el ejemplo.

DocBlock y documentación autogenerada

Algunos editores de texto añaden documentación de forma más o menos automática que permite indicar los tipos de los argumentos y del valor devuelto, así como información adicional.

Veamos un ejemplo

    /**
     * get movements
     *
     * @return array
     */
    public function getMovements()
    {
        return $this->movements;
    }

Este tipo de documentación no aporta ningún valor adicional ya que simplemente está repitiendo lo mismo que ya dice el nombre de la función. Quizá esto tenía sentido antes de la versión 7, para ayudar al IDE en el autocompletado. Pero a partir de esta versión es mucho mejor eliminar estos comentarios y utilizar el tipado nativo del lenguaje.

   public function getMovements(): array
    {
        return $this->movements;
    }

Usos permitidos

Por supuesto el autor contempla algunos casos en los que sí estaría permitido y justificado el uso de comentarios.

Licencias y textos legales

Es un uso completamente justificado el incluir la licencia y otros textos legales en el encabezado de nuestros ficheros. Además esto no supone ningún trabajo adicional, por que es habitual utilizar sistemas que se encargan de añadir estos comentarios de forma automática, y además los IDE suelen ocultarlos por lo que no molestan.

APIs

Si estás construyendo una api y probablemente quieras generar la documentación a través de algún sistema automático, sí estaría justificado el incluir toda esta información adicional en tu código.

Confunden al lector

En general los argumentos booleanos confunden al lector. Veamos un ejemplo, con una clase del componente Config. Esta clase en concreto es la responsable de buscar un fichero de un determinado nombre en un array de paths definidos en los que se podría encontrar.

namespace Symfony\Component\Config;

/**
 * FileLocator uses an array of pre-defined paths to find files.
 */
class FileLocator implements FileLocatorInterface
{
    // ..
    public function locate(string $name, string $currentPath = null, bool $first = true)
    {
        // ..
    }
   // ..
}

¿Sabrías decirme qué hace exactamente el tercer argumento? Quizá tengas la siguiente intuición, si le pasamos true probablemente devolverá la primera coincidencia, pero ¿qué ocurre si le paso un false?. Si realmente quiero entender esta función voy a necesitar ir al código y leer que es lo que hace.

Una vez que ya nos hemos leído el código entendemos que el funcionamiento es el siguiente:

• si le paso un true, me devolverá la primera coincidencia
• si le paso un false me devolverá todas.

¿No se lo pondríamos mucho más fácil al lector si somos explícitos de esta forma?

namespace Symfony\Component\Config;

/**
 * FileLocator uses an array of pre-defined paths to find files.
 */
class FileLocator implements FileLocatorInterface
{
    // ..
    public function locateAll(string $name, string $currentPath = null)
    {
        // ..
    }

    public function locateFirst(string $name, string $currentPath = null)
    {
        // ..
    }
   // ..
}

Como siempre esto no significa que debamos duplicar el código, ya que probablemente podemos encontrar la forma de que uno llame a otro o utilizar funciones privadas más pequeñas, para evitar cualquier duplicidad.

Hace dos cosas

En muchas ocasiones un argumento booleano indica que la función hace dos cosas diferentes. Como ya vimos en la entrada dedicada a funciones, estas deberían hacer una única cosa y deberían hacerla bien.

Veamos un ejemplo con el componente DomCrawler de Symfony. Este componente permite crear un cliente que simula ser un navegador y que se utiliza en pruebas funcionales y para tareas de scrapping.

La función que vamos a ver se llama después de haber ejecutado una query sobre un documento HTML $message = $crawler->filterXPath('//body/p')->text();

namespace Symfony\Component\DomCrawler;

/**
 * Crawler eases navigation of a list of \DOMNode objects.
 */
class Crawler implements \Countable, \IteratorAggregate
{
    // ..
    /**
     * Returns the text of the first node of the list.
     *
     * Pass true as the second argument to normalize whitespaces.
     */
    public function text(string $default = null, bool $normalizeWhitespace = true)
    {
        // ..
    }
    // ..
}

¿No da la sensación de que el segundo argumento responde a una necesidad del programador que a una decisión de diseño? ¿Quién realizaría un diseño así? Obviamente el siguiente ejemplo es mejor.

namespace Symfony\Component\DomCrawler;

/**
 * Crawler eases navigation of a list of \DOMNode objects.
 */
class Crawler implements \Countable, \IteratorAggregate
{
    // ..
    public function text(string $default = null)
    {
        // ..
    }

    public function normalizeWhitespace(string $text)
    {
        // ..
    }
    // ..
}

Y una vez realizado este diseño, ¿no parece evidente que normalizeWhitespace debería ir en otra clase? esto lo veremos más adelante en la entrada dedicada a las clases.

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.

La mayoría de las empresas de desarrollo de software optan por realizar un largo documento explicativo con información sobre la herramienta, algo así como una enorme guía. Nosotros no creemos en este método, documentamos de una manera totalmente distinta y que ha aportado gran valor a cada uno de nuestros clientes.

En este artículo, te contaremos porqué en DEVTIA no documentamos, y cómo logramos obtener resultados mejores que redactando un enorme manual que nadie va a leer.

¿Por qué no documentamos?

Son tres simples motivos los que nos llevaron a tomar la decisión de no documentar, o al menos no de la manera tradicional:

1. Recuerda la última vez que compraste un electrodoméstico, ¿te leíste la guía de instrucciones entera, o quizás, solo te concentraste en buscar cómo se configuraba el wifi? Algo similar pasa con el desarrollo software, nunca o casi nunca se va leer un documento de estas características completamente, así que decidimos no incluirlo. Consideramos que es una pérdida de tiempo tanto para nosotros como para el cliente en caso de que decida leerlo.
2. Desactualización. La documentación se desactualiza casi al momento de realizarla y más cuando se trata de desarrollos que se encuentran en constante transformación y en el que se incluyen funcionalidades que pueden cambiar el funcionamiento de la herramienta radicalmente.
3. Cada cliente es un mundo. Si quisiéramos realizar una documentación para cada tipo de cliente tardaríamos semanas en hacerlo y si quisiéramos hacer uno genérico no encontraríamos la forma de que todos los clientes lograran mostrarse satisfechos con él.

Entonces, ¿cómo lo hacemos?

Antes de explicártelo, nos gustaría especificar que todo lo que vamos a exponer a continuación, está vivo y en constante cambio jugando el cliente un papel fundamental en ello.

En tu idioma

Cuando se trabaja con herramientas genéricas muchas veces ocurre que estas no están disponibles en el idioma del cliente. El usuario final no entiende completamente los mensajes de la plataforma y esto hace que se puedan producir errores o confusiones al existir términos diferentes. Nosotros lo tenemos muy claro: absolutamente todo en el idioma del cliente.

Tu aplicación tu lenguaje

Utilizamos el lenguaje propio del cliente, que es un factor capital. Cada campo de la herramienta que vaya a ser utilizado en la empresa ha de ser fácilmente reconocible para cualquiera de los trabajadores que la utilicen. Por ello, priorizamos el lenguaje que el cliente utiliza para denominar a cada uno de los campos, menús y casillas que componen el sistema de la manera que más les convenga.

Por ejemplo, si en tu empresa cuando a una persona interesada en vuestro producto os deja sus datos de contacto lo denomináis “solicitud”, aparecerá “solicitud” en cada uno de los mensajes y textos designadas para ello en lugar de cualquier otra denominación como, por ejemplo,“lead” u "oportunidad" que es como se suele denominar de forma más generica. Esto hace que tu equipo se familiarice con la terminología de la herramienta desde el primer día.

Bloques de ayuda y menús contextuales

Creemos que el mejor sitio para almacenar la documentación es la propia aplicación. Por eso cada vez que un cliente nos hace una pregunta, del tipo, ¿cómo funciona esto? ¿cómo se calcula exactamente ese dato? se lanzan dos acciones. Además de resolver la duda acudimos a la pantalla o pantallas que originaron la duda del cliente y completar la información allí mismo, generamos una leyenda que sirva como "guía de posibles problemas a resolver".

Añadimos menús contextuales o información en bloques de ayuda en los que, colocando el cursor del ratón encima, aparecerá una breve descripción del elemento y que hemos considerado relevante como podría ser una determinada fórmula, un nuevo término incluido en la herramienta o información acerca de un comportamiento. Veamos un ejemplo.

Módulo de ayuda

Es habitual que durante el desarrollo de una aplicación el equipo de desarrollo genere diferentes esquemas, tablas, etc que les permitan tanto entender lo que tienen que hacer como para que el cliente los valide antes de ponerse manos a la obra. Muchas veces esta información tan importante se pierde en tu gestor de correo y con el paso de los meses o incluso de los años es posible que nadie sepa donde está.

Por eso nosotros implementamos dentro de un módulo de ayuda todos los esquemas y tablas que generamos durante el proceso de desarrollo. De esta forma se nos facilitan las siguientes tareas.

1. Tenerlo siempre disponible.
2. Que no se pierda.
3. Mantenerlo fácilmente actualizado. Si te piden un cambio, primero cambias el esquema y luego la propia aplicación.

Consistencia en la estructura

Todos nuestros desarrollos suelen disponer de una estructura bastante similar que planificamos adhoc. Los listados de todos los elementos de la herramienta (contactos, facturas, miembros del equipo…etc) van a ser iguales en su funcionamiento para que no se produzcan confusiones y para que el aprendizaje de la herramienta se agilice entre los empleados. Lo mismo pasa con cada una de las fichas que forman parte del desarrollo.

Una vez que te familiarices con la estructura con la que trabajamos te será muy intuitivo entender nuevos módulos incluso aunque nadie te los explique.

Menús y breadcrumbs

Creemos que es necesario utilizar menús tanto horizontales como verticales que te acompañen en todo momento durante la utilización de nuestras soluciones digitales y que te permitan saber exactamente donde estás y que opciones tienes disponibles.

Módulo de auto ayuda

El lenguaje propio utilizado en una empresa es un factor determinante para que se desarrolle una buena comunicación entre empleados y para que, al empezar a utilizar una nueva herramienta, todos y cada uno de los componentes de la plantilla obtenga un nivel similar en la comprensión de su uso.

En todos nuestros desarrollos incorporamos un módulo al que llamamos de “autoayuda” al que tendrán acceso todos los miembros del equipo. Este módulo consiste en que en cada pantalla, hay un bloque de ayuda que puede cambiar cualquier miembro del equipo con los permisos adecuados. Es una forma de que el cliente, pueda completar la información que nosotros ya hemos incluido en el sistema, sin la necesidad de que nosotros participemos en ese proceso.

Logramos así, que además de la ayuda que nosotros ofrecemos, los usuarios de las herramientas se retroalimenten del conocimiento de toda la plantilla.

En Devtia, somos expertos en las plataformas CRM, que ayudan alcanzar este trato exclusivo. En este artículo te contamos todo lo que debes saber sobre estas plataformas que han revolucionado el mundo empresarial.

¿Qué es CRM?

Un CRM (Customer Relationship Management) es una herramienta que a través de la combinación de prácticas, estrategias y ciertos procedimientos tecnológicos logran gestionar las interacciones y estadísticas de clientes o leads a lo largo de su relación con la empresa. Uno de los principales objetivos del CRM es mejorar y optimizar estas relaciones, con el objetivo de hacer de un lead un cliente fidelizado.

Los sistemas CRM recopilan información y datos de clientes a través de los distintos canales de los que la empresa dispone tales como sitio web, redes sociales, correo electrónico, teléfono, whatsapp y diversas estrategias de marketing como podría ser la publicidad en motores de búsqueda.

Un CRM básico sería aquel que:

• Ayuda a tener una base de datos segmentada
• Consultar ventas
• Consultar la comunicación existente entre empresa y clientes e incluso o
• Automatizar procesos.

En las versiones más avanzadas se puede hacer “magia” utilizando técnicas de predicción para acabar sugiriendo nuevos productos que encajen con el perfil del cliente (tal y como hace, por ejemplo, Amazon). Además de añadir numerosas funciones adicionales que hacen que un CRM se vuelva mucho más útil.

Beneficios de un CRM

1. Mejora la información del negocio.
2. Automatización de tareas.
3. Analítica de los datos e informes disponible en pocos clics.
4. Aumento de la eficiencia y reducción de tiempos.
5. Comunicación entre departamentos más satisfactoria.

Caracterísicas de un CRM

Para que una herramienta CRM sea capaz de obtener el máximo rendimiento en cada una de las acciones que se realicen en ella, debería estar formado por los siguientes componentes:

• Gestión de tu base de datos de contactos: Es la razón de ser de un CRM, el elemento principal. Con este tipo de herramientas tendrás una interfaz donde podrás acceder a todos los contactos que se ha considerado que deben aparecer en él. También se podrá consultar cualquier dato referente al contacto; nombre, apellidos, correo, número de teléfono...etc.
• Gestión de llamadas, correos y tareas: a través del propio CRM y sin necesidad de utilizar herramientas externas, se podrán programar correos a enviar al contacto, agendar una llamada pendiente de hace tiempo, gestionar las tareas que se han de realizar con este contacto y cualquier otra acción que facilite la comunicación y la eficiencia. El resumen de las acciones pendientes del cliente podrán verse en el escritorio de la herramienta, facilitando la gestión al personal de la empresa.
• Histórico de interacciones con el cliente: toda acción que se realice quedará registrada en el programa (llamadas, si coje el teléfono, compra de producto, actitud del cliente ante determinadas ofertas, cómo se obtuvo ese contacto...). De esta manera, todo el equipo tendrá acceso a todas las acciones que se han realizado con un determinado cliente y se facilitará el orden y el control de la empresa. La gestión entre compañeros será mucho más eficiente con esta característica del CRM.
• Propuestas personalizadas: La capacidad de crear ofertas con un distinto grado de personalización dependiendo del tipo de cliente, siendo enviadas con un solo clic, es una de las grandes ventajas que pueden ofrecer los CRM. No todos tienen capcidad para realizar este tipo de propuestas, pero los que Devtia realiza, a no ser que el cliente indique lo contrario, lo tendrán.
• Vinculado al departamentos importantes de la empresa: Cualquier registro o movimiento que el cliente realice llegará a todas las áreas que estén incluidas en el sistema. De esta manera, por ejemplo, un cliente que manifiesta su interés a través de un comercial en adquirir un vuelo, será traspasado al departamento de producción para que finalice el proceso de adquisición del mismo.
• Informes y alertas: El reporting, necesario en cualquier ámbito empresarial, estará muy presente en cada una de las herramientas del software, pudiendo acceder a datos relevantes al instante. Además, en casi todos los CRM, se pueden programar determinadas alertas que sean trascendentes para la actividad comercial de la empresa; una llamada, una reunión de un departamento de la empresa o un día señalado en el calendario dada su importancia a la hora de lanzar una nueva campaña online, hay muchas opciones para personalizar estas notificaciones.
• Cuestionarios y encuestas de satisfacción: Saber y conocer a la perfección cuáles son los factores que aumentan la satisfacción y cómo de contentos se encuentran los consumidores con la relación existente con la empresa, es primordial. Realizar encuestas y cuestionarios para conocer lo anterior, es un proceso que se puede realizar en la plataforma facilmente y que aportará datos de gran importancia que podrán servir de precedente para realizar cambios importantes.
• Geolocalización: algunos sistemas CRM incluyen servicios de geolocalización que ayudan a crear campañas de marketing basadas en ubicaciones físicas de las personas.
• Inteligencia artificial: aunque parezca futurista, la IA ya está más que incorporada en los sistemas CRM. Ayuda a identificar patrones repetitivos de compra para, por ejemplo, predecir el futuro de su comportamiento y enviar ofertas según sus movimientos.

Devtia y CRM

Somos expertos totales en CRM, actualmente estamos trabajando con:

• Salesforce: un software de CRM que ayuda a las empresas a conectarse con sus clientes utilizando la tecnología cloud, de la que ya os hablábamos en este artículo. Es uno de los softwares más prestigiosos y con más renombre, además de uno de los más utilizados.
• Hubspot: la herramienta de inbound marketing por excelencia. Esta herramienta ha adquirido gran popularidad entre los profesionales del marketing, aunque su rendimiento en cualquier ámbito es excelente.
• CRM desarrollados a medida según las necesidades del cliente: como te hemos explicado en numerosos artículos, este es nuestro producto estrella y uno de los motivos por lo que nació nuestra empresa. Infórmate en estos artículos;