Convenciones que un recién llegado puede deducir

Una convención cuenta solo si un recién llegado puede adivinarla correctamente sin preguntar. Si tiene que preguntar, es un secreto, por bien documentado que esté.

Este es el argumento práctico más fuerte para quedarse cerca de Laravel. Un desarrollador que ha trabajado en cualquier aplicación de Laravel ya sabe dónde vive un FormRequest, qué hacen index y store y cómo se despacha un job. Cada convención que tomas del framework es una que tu recién llegado trae sabida.

Para las pocas que son tuyas, hay dos maneras de hacer que sea imposible pasarlas por alto.

Genéralas. php artisan stub:publish copia las plantillas que hay detrás de cada comando make: a un directorio stubs/ de tu proyecto. Edítalas una vez, para añadir declare(strict_types=1) o un docblock que tu equipo siempre escribe, y toda clase que alguien genere a partir de entonces nace siguiendo la regla. (Documentación de Laravel: Artisan Console › Stub Customization.)

Imponlas. El test de arquitectura del Capítulo 12 convierte «los controladores nunca llaman directamente al proveedor» en un build que falla. Un comentario que dice lo mismo queda obsoleto en el momento en que alguien deja de leer comentarios. Un build que falla, no.

Documentación que sobrevive a los cambios del código

La documentación escrita a mano es exacta el día que la escribes y falsa algún día posterior, y nadie puede decirte cuál.

La mayoría de los equipos responden a esto programando revisiones de la documentación. No funciona. La revisión ocurre según un calendario, el código cambia según un pipeline de despliegue, y los dos ritmos nunca coinciden. Más disciplina no lo arreglará. Haz que la documentación sea algo que generas, o algo que falla cuando es falsa.

• Los tests son la documentación del comportamiento. «Un 404 al borrar se trata como un éxito» está escrito en el Capítulo 12 como un test. No puede desviarse, porque se ejecuta.
• Los tests de arquitectura son la documentación de la estructura.
• Las pautas para los agentes de programación también pueden generarse. Laravel Boost las produce a partir de los paquetes realmente instalados en el proyecto, así que php artisan boost:update reemplaza la búsqueda de un párrafo que corregir.

Lo que queda para la prosa es la parte que solo una persona puede escribir: el porqué. Por qué el borrado se encola, por qué el binding del driver es scoped. Que esas notas sean cortas y estén junto al código que explican, en el mismo pull request que el cambio. Es el único lugar donde una actualización de la documentación sobrevive con seguridad.