«Clean Code» sin escribir una linea de código

Como desarrolladores nuestro trabajo es escribir código que ayude a resolver problemas, ni más ni menos que eso. Resolver problemas. Leemos libros como Clean Code, Software Craftmanship,… estamos al día de las últimas tendencias sobre programación, conocemos lenguajes, frameworks, en definitiva intentamos cada día hacerlo un poco mejor.

Pero, ¿es todo escribir código? da igual que sea PHP, Python, Javascript o Java nuestro día a día es resolver problemas y hacerlo bien. Una de las razones podría ser no generar demasiada deuda técnica y que nuestro código tarde más en convertirse en legacy code.

Además debemos luchar contra los deadlines,  así que en este post vamos a ver una serie de consejos para escribir mejor código sin escribir código.

Lee más código del que escribas

Por cada linea de código que escribamos deberíamos leer 10 o más lineas. Así tomaremos ideas de como hacer que nuestro código sea más legible y eso lo agradeceremos en el futuro y lo agradecerán nuestros compañeros.

Lee y piensa antes de escribir

Pero no solo tenemos que leer código, también libros y no solo técnicos sino de lo que más nos guste. Da igual que sea el último libro de Megan Maxwell o un cómic de Spiderman, leyendo enriquecemos nuestro vocabulario y eso nos hará mejores programadores.

Naming

Es algo que tenemos que hacer cada día varias veces, nombrar funciones, variables clases así que invirtamos tiempo en nombrar bien. Si llamamos a una variable $result, o $x lo lamentaremos sobre todo en el futuro busca hasta encontrar el nombre ideal. Un buen nombre nos ayuda a entender mejor el código y la intención con la que lo escribimos.

Un buen naming nos ayudará a que el salto entre nuestra solución y el código sea menor.

Asumámoslo, nos equivocamos. No tengamos miedo a refactorizar y cambiar de nombre 100 veces si hace falta. Utiliza thesaurus.com o un diccionario de sinónimos llamar a una variable.

Si aun así no encontramos un buen nombre quizás sea mejor que llamemos a la variable $ramon $pepe algo que «llame la atención» para que más adelante podamos pensar un poco mejor el nombre y no perder el foco de la tarea. Si todas tus variables empiezan a tener nombre de personas…

Sobre el naming de los métodos sería bueno que intentemos que los métodos públicos se lean de manera sencilla, sin que tengamos que pensar en demasiadas condiciones o bucles complicados

class CourseService {
    
    ...
    
    public function signUp(SmartCode $code, User $user)
    {
        $this->checlThatSmartCodeIsValid($code);
        
        $course = $code->getPayload();
        $this->checkThatUserIsNotSignedUp($user, $course);
        
        $this->smartCodeService->register($user, $code);
        
        return $this->smartCodeEnrollment->enroll($user, $course);
    }
    
    ...
}

Con un buen naming también estamos ayudando a crear una buena estructura de nuestro código. Los nombre buenos hace que escribamos menos documentación y que nuestro código quede «autodocumentado»

Organización de ficheros y carpetas

Tenemos que ser organizados, el camino para escribir clean code empieza con una buena estructura de carpetas. A veces los frameworks nos ayudan a tener una buena estructura de carpetas, sino siempre podemos tener a mano libros como «DDD in PHP» o leer código para tener ideas 😉

Como hemos comentado antes no debemos tener miedo a cambiar la estructura de carpetas para adaptarla a nuestras necesidades y renombrar también las carpetas para hacer la estructura más entendible.

Usar carpetas para separar conceptos

Del mismo modo una buena documentación es imprescindible y no me refiero solo a PHPDocBlocks sino a un buen Readme, buenos diagramas de flujo y diagramas de clase.

Con todo esto, la organización que hagamos del código, la generación de documentación, los diagramas,… tenemos que crear un lenguaje que encaje en nuestro proyecto, un lenguaje ubicuo, que no dependa de la programación, un «idioma» que nos ayude a comunicarnos con todos los implicados en el proyecto.

PSR y code style

Estándar de código, abrir las llaves en una nueva linea, la indentación de 4 espacios, el espacio en la guarda de un if, … son chorradas pero son esas chorradas que nos hacen la vida más fácil.

Cuando abrimos una nueva clase y nos la encontramos manga por hombro… nos hace perder tiempo. Perdemos tiempo buscando y haciendo scroll, invertimos tiempo leyendo el código, perdemos más tiempo de la cuenta intentando entender la solución. Así que lo mejor es que configuremos PHPStorm para utilizar el estándar de código que queramos (PSR-2), también podemos utilizar PHP-CS-Fixer para aplicar estilo a nuestro código.

Escribiremos el código que nos gustaría encontrarnos en el futuro

Mensajes de commits

Tener buenos mensajes de commits nos ayudará a entender porqué hicimos algo. Cuando encontramos un bug y buscamos la solución, normalmente llegamos a una clase, a un método y vemos que algo está incorrecto y siempre pensamos ¿por qué hice esto? ¿en que estaría pensando?

Así que tener un buen mensaje de commit nos ayuda a saber qué paso. Lo mismo pasa cuando resolvemos el bug. poner un mensaje que dice fixing bug pues… lo mismo ocurre cuando nuestro mensaje es fix #TICKET-12345 es algo porque nos da información pero… del mismo modo escribir refactor o just a renaming mejoramos el código pero por qué es un buen nombre

Un buen mensaje de commit sería algo así como:

TIC-123: Method for obtain the last in JSON format

We are adding a new method in the API so we can integrate in the future easier in our mobile app. These methods aren't used in the frontend.

Una buena herramienta que puede ayudarnos en esto es GrumPHP con ella creamos un hook para Git que chequea una lista de requisitos antes de hacer un commit, desde que para tener un commit tengamos una tarea de Jira hasta contar el número de caracteres del mensaje de commit.

Cuando escribimos el mensaje debemos buscar el porqué estamos haciendo el cambio. No queremos saber que ha cambiado, eso lo vemos en el diff, por eso sería necesario que pongamos énfasis en el porqué.

Nos es de gran ayuda hacer commits pequeñitos y muy enfocados, así nos será más fácil escribir mensajes de commits. De la misma manera, si hemos llegado a leer los mensajes de commits seguramente solo sea porque estamos investigando la raiz de un problema así es necesario que tengamos esto en mente cuando lo escribamos.

Conclusiones

En resumen para escribir mejor código sin escribir código debemos tener en cuenta:

• Leer más código del que escribes
• Naming: disminuir el salto entre el código y la solución — Buenos nombres a los métodos y clases
  • Hacer que métodos públicos se lean sin dificultad
• Organización de ficheros y carpetas
• Code Style
• Mensajes de commits

Estos son algunos de los elementos que nos ayudarán a escribir mejo código, pero seguro que hay más y mejor. Os animo a compartirlos en los comentarios. Seguro que entre todos podemos encontrar más puntos a tener en cuenta.