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.

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.

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.

Más lento para ir más rápido

A lo largo de este primer capítulo Martin nos introduce la idea de que en muchos proyectos cuando se trata de ir demasiado deprisa el resultado es exactamente el contrario. Si eers programador probablemente hayas vivido esto en tus propias carnes. En el periodo de uno o dos años en los que los programadores han ido añadiendo cambios al código sin control el resultado es que cada vez se hace más y más difícil avanzar y se dedica la mayoría del tiempo a solucionar incidencias. Para añadir cualquier pequeño cambio es necesario tener en cuenta un sin fin de detalles, efectos y consecuencias, así que cada nueva funcionalidad añade aún más complejidad al proyecto.

La solución que aplican muchos managers en este momento es aumentar la plantilla, pero sin cambiar la forma de trabajar, lo que fragmenta más el código y reduce cada vez más la productividad. Más pronto que tarde el equipo de desarrollo se plantará y exigirá "rehacer" el código para sacar una nueva versión, esta vez sin los problemas de la actual. Pero recuerda que si no cambian su forma de trabajar y de pensar, el mismo equipo que generó el problema volverá a generar un problema parecido de nuevo.

Si te has visto en esta situación te aconsejo leer esta serie de entradas sobre código limpio.

Bien, ¿Pero qué es el código limpio?

El libro autor comienza haciéndose el mismo esta pregunta. Para ello recurre a diversos autores relevantes a los que les traslada esta cuestión.

¿Qué conclusiones sacamos?

De todas estas entrevistas se extraen una serie de ideas más o menos comunes.

Que haga lo que se espera que haga

Nosotros en DEVTIA a esta regla la llamámos: "No me mientas". Es también muy fácil de entender cada función y cada clase tiene que hacer exactamente, lo que se espera que haga. Además esto debe ser evidente, no debo necesitar entrar a ver el método para saber que puedo esperar de el.

Pequeño

Esta es una regla fácil de seguir y fácil de entender. Cuanto más pequeño sea nuestro código más fácil será que podamos modificarlo y mantenerlo. Dependerá de cada proyecto y de cada equipo establecer los límites, pero un buen punto de partida podría ser que las funciones y las clases con sus métodos colapsados deberían poder visualizarse completamente en las pantallas que está usando el equipo.

En los siguientes capítulos veremos muchos ejemplos para mejorar este aspecto.

Sin duplicidad

Un error claro de diseño es cuando necesitas copiar y pegar tu código en diferentes sitios. A la larga esto va a introducir errores, ya que cuando alguien actualize una copia, probablemente olvidará actualizar las demás.

Debe tener tests

Casi todos los autores han introducido la importancia de los tests. Tener una buena batería de test nos va a permitir trabajar con nuestro código y poderlo modificar con seguridad de que si estamos rompiendo alguna cosa, los test nos van a avisar.

La regla del boy scout

La regla del Boy Scout se trata de una regla muy sencilla. Originalmente se refiere a lo que hacen los Boy Scout cuando hacen una acampada: dejan el lugar en el que han estado un poco más limpio de como se lo encontraron.

Aplicado al desarrollo de software nos indica que si en nuestro día a día según estamos trabajando en un proyecto podemos ir introduciendo pequeñas mejoras que el autor original no tuvo en cuenta, pero que para nosotros son evidentes. Estos pequeños cambios, en los que podemos incluir desde cambio de nombres, extracción de métodos, pequeños refactorizaciones, solución de bugs, ect, a lo largo de un periodo de tiempo generará un grado de maduración en el código.