Où commencer quand plus personne ne comprend un bloc hérité d’un ancien collègue

Par où commencer quand un bloc personnalisé, installé depuis des années sur un site, ne comporte ni fichier readme, ni commentaire explicatif, ni le moindre test, et que la personne qui l’a écrit a quitté l’équipe depuis longtemps ? La tentation immédiate consiste à ouvrir edit.js et à corriger le symptôme signalé. C’est presque toujours la mauvaise première étape.

Un bloc « Bloc catalogue » gérait, dans ce cas précis, l’affichage d’une sélection de références produits sur les pages d’accueil d’un site vitrine. Le ticket initial semblait simple : « le tri par nouveauté ne fonctionne plus depuis la dernière mise à jour du thème ». Trois attributs mal nommés plus tard, il est apparu que le bloc gérait en réalité deux logiques de tri concurrentes, l’une héritée d’une ancienne version jamais nettoyée, l’autre ajoutée plus tard sans supprimer la première.

Cartographier avant de toucher au code

La première étape utile n’est pas la correction, mais l’inventaire. Lister systématiquement les attributs déclarés dans block.json, puis vérifier, en interrogeant la base de données ou en exportant le contenu (wp export ou une requête directe sur la table wp_posts), lesquels sont réellement utilisés en production et avec quelles valeurs. Il n’est pas rare de découvrir des attributs déclarés depuis des années, jamais renseignés par aucun rédacteur, qui n’existent que pour justifier un contrôle d’inspecteur devenu inutile.

Repérer les blocs orphelins d’un premier coup d’œil

Une requête simple permet de vérifier rapidement combien d’articles contiennent effectivement le bloc concerné, et sous quelle forme :

wp post list --post_type=page --format=ids | xargs -I{} wp post meta list {} 2>/dev/null
grep -rl "wp:mon-agence/bloc-catalogue" wp-content/uploads/exports/*.xml

Cette étape, souvent négligée par impatience de corriger, évite de perdre du temps sur des cas d’usage qui n’existent en réalité dans aucun contenu publié.

Isoler la logique dupliquée avant de la corriger

Une fois l’inventaire fait, il devient possible de repérer la logique réellement active. Dans ce cas, deux blocs de conditions cohabitaient dans render.php : l’une héritée d’une variable $atts['ordre'] issue d’un ancien shortcode jamais retiré du code, l’autre basée sur l’attribut moderne tri du bloc. La première ne recevait plus jamais de valeur depuis la migration vers le bloc, mais continuait à s’exécuter en premier, masquant silencieusement la seconde dans certains cas de figure.

Écrire un test avant la première correction

Avant toute modification, un test de non-régression, même minimal, protège des corrections qui semblent fonctionner en local mais cassent un cas non testé manuellement. Pour un bloc dynamique, un test PHPUnit qui appelle directement la fonction de rendu avec plusieurs jeux d’attributs suffit souvent :

public function test_tri_par_nouveaute_ignore_l_ancien_attribut_ordre() {
	$html = render_bloc_catalogue( array(
		'tri'   => 'nouveaute',
		'ordre' => 'ancien', // attribut hérité, ne doit plus influencer le rendu
	) );

	$this->assertStringContainsString( 'data-tri="nouveaute"', $html );
}

Ce test, écrit avant la correction, échoue d’abord pour de mauvaises raisons (la logique héritée gagne encore), ce qui confirme le diagnostic avant de toucher au code.

Nettoyer par étapes, jamais en un seul passage

• Retirer la logique morte identifiée, sans toucher encore aux attributs déclarés dans block.json.
• Marquer les attributs inutilisés comme dépréciés via une entrée deprecated plutôt que de les supprimer immédiatement, pour ne pas casser les contenus existants qui les contiendraient encore.
• Documenter, même sommairement, ce qui vient d’être compris, pour la prochaine personne qui reprendra ce bloc.

Sur ce genre de reprise, nous consacrons systématiquement un temps équivalent à l’investigation qu’à la correction elle-même : c’est ce temps d’inventaire, pas la correction en elle-même, qui évite de recréer un second bug six mois plus tard.

Ce que cette reprise a réellement coûté

Dans ce dossier, l’inventaire et l’écriture du premier test ont représenté plus de la moitié du temps total passé sur le ticket initial. La correction proprement dite, une fois le diagnostic posé, a tenu en une dizaine de lignes retirées. Le déséquilibre est volontaire : un bloc sans documentation impose de reconstruire mentalement les intentions de son auteur avant de pouvoir y toucher sans risque.

En résumé

Reprendre un bloc hérité sans documentation demande de résister à l’envie de corriger immédiatement le symptôme signalé. Cartographier les attributs réellement utilisés, isoler la logique dupliquée, écrire un test avant toute modification : cet ordre, bien plus lent en apparence, évite de transformer une correction ponctuelle en une nouvelle source de bogue silencieux.