Buenas Prácticas: Corregir el estilo de código antes de hacer Commit

Captura de pantalla 2020-04-01 a las 9.13.32.png
Solucionex
01
Abr 20

La capacidad de trabajar en equipo o de que el proyecto que estemos desarrollando perdure en el tiempo puede depender en gran medida de cómo hayamos escrito el código y de las facilidades que le demos al que tenga que leer ese código.

Además, escribir todos igual refuerza al propio lenguaje en si en el que trabajamos, el hecho de definir una serie de normas, reglas o estándares a la hora de escribir hacen que el mismo PHP acabe reforzado, ya que cualquier persona de la comunidad puede leer el código.

PSR-2

Aunque no todos los programadores utilizan este estilo de codificación, el estándar más extendido es el PSR-2, si quieres ampliar información sobre qué esto del PSR, en este enlace puedes hacerlo: https://www.startutorial.com/articles/view/modern-php-developer-psr

Bien, concretando y resumiendo mucho, PSR-2 nos dice exactamente dónde hay que poner las llaves de cada función, con cuántos espacios se tabula el código...

¿Cómo sé que mi código está escrito correctamente?

Utilizaremos una herramienta llamada php-cs-fixer (https://github.com/FriendsOfPHP/PHP-CS-Fixer), y mi recomendación es tenerla instalada en el ordenador en el que desarrolles de forma global, aunque esto ya lo decides tú, si es lo que buscas, sigue estos tres sencillos pasos:

  1. $ wget https://cs.symfony.com/download/php-cs-fixer-v2.phar -O php-cs-fixer
  2. $ sudo chmod a+x php-cs-fixer
  3. $ sudo mv php-cs-fixer /usr/local/bin/php-cs-fixer

Lanzando esos tres comandos, te descargarás primero php-cs-fixer, después lo harás ejecutable y en el tercero creamos el "acceso directo", de esta manera, escribiremos "pcp-cs-fixer" en la línea de comandos desde cualquier ubicación y podremos lanzarlo.

Para comprobar qué ficheros están correctamente escritos lanzaremos el comando:

php-cs-fixer fix PATH --rules=@PSR2 --dry-run

Importante utilizar la opción "--dry-run" para que no se produzcan cambios y en PATH escribir la ruta del proyecto. Este comando nos dirá qué ficheros no están correctamente escritos.

Corrección automática de ficheros con php-cs-fixer

Si lo que deseamos es que la herramienta nos corrija el código, el mismo comando anterior lo podemos lanzar pero sin la opción "dry-run". Mi recomendación es no hacer esto en un proyecto completo, si no corregir ficheros uno a uno para mantener el código que cambia php-cs-fixer más controlado.

php-cs-fixer fix PATH --rules=@PSR2

Ten en cuenta que el parámetro "rules" indica el estándar de codificación por si quieres utilizar otro. También en su repositorio puedes ver las distintas opciones que tiene el comando.

Comprobar el código antes de subir al repositorio

Hasta aquí una breve introducción para entender qué es php-cs-fixer y cómo utilizarlo, pero lo que realmente nos interesa en nuestro día a día es trabajar de una manera ágil, rápida y con todos los automatismos posibles. Y tener que comprobar cada fichero que cambiamos de un proyecto con php-cs-fixer se puede hacer pesado.

Vamos a implementar el hook pre-commit de git, de esta manera cada vez que queramos hacer un commit, no nos lo permitirá si el código de los ficheros cambiados no está en PSR-2. El código del hook será el siguiente:

#!/bin/bash

exec 1>&2

ROOT_PATH=$(git rev-parse --show-toplevel)
CHANGED_FILES=$(git diff --cached --name-status | awk '$1 != "D" { print $2 }')
CS=""

for FILE in $CHANGED_FILES ; do
    if [[ $FILE =~ ^src/.+\.(php|twig|yml|phtml)$ ]]; then
        CHANGE=$(php-cs-fixer fix $ROOT_PATH/$FILE --rules=@PSR2 --dry-run --using-cache=no | sed '$ d' | cut -d ')' -f 2)
        if [ ! -z "$CHANGE" ] ; then
            CS="$CS\n    $FILE"
        fi
    fi
done

if [ ! -z "$CS" ] ; then
    echo -e "The following files do not conform with FIG PSR-2:
$CS

Fix them in order to commit."
    for FILE in $CS ; do
        git reset $FILE
    done
    exit 1
fi

exit 0

Esto lo guardaremos en un fichero ejecutable dentro de la carpeta del proyecto .git/hooks/pre-commit y se ejecutará automáticamente en cada commit, avisándonos para que corrijamos la codificación de los ficheros que sea necesaria.

Una vez que hayas corregido el estilo del fichero problemático, y te sugiero que lo hagas "a mano", y no pasando el comando php-cs-fixer, para controlar mejor qué código se cambia, tendrás que volver a añadir el fichero al commit con "git add".

¿Cómo corregimos un fichero antiguo que no seguía ningún estilo?

Nos va a pasar a veces que nos encontraremos ficheros que no están en ningún estilo y queremos empezar a aplicarlo. Mi experiencia, para facilitar más tarde la lectura del proceso de desarrollo, dice que hagas un solo commit con la corrección del código, y después apliques los cambios para el correcto desarrollo del proyecto.

De esta manera, cuando veamos el timeline del proyecto veremos dos commits:

  • "Corregir codificación del proyecto"
  • "Corregir bucle infinito" (por ejemplo)

Mientras que si lo hacemos en un solo commit, no vamos a poder leer los cambios que hicimos en el commit "Corregir bucle infinito" porque el fichero marcará que se cambiaron todas las líneas debido a la corrección de las tabulaciones.