Le fichier de configuration qui s'explique lui-même

Le .htaccess de ce serveur fait 478 lignes. 98 d'entre elles sont des règles. 309 sont des commentaires.

Trois lignes d'explication pour chaque ligne qui fait quelque chose. Ce rapport n'a pas été planifié ; c'est ce qui arrive quand la règle pour écrire une règle est que la raison doit se tenir à côté.

Pourquoi une règle de réécriture a besoin d'un paragraphe

Une règle dans une configuration de serveur est exceptionnellement hostile à une lecture ultérieure. Elle est laconique par nature, elle n'a pas de nom, on ne peut pas l'exécuter pas à pas, et son effet est invisible tant qu'on ne demande pas justement la bonne adresse. Six mois plus tard, la seule réponse honnête à « pourquoi est-ce là » est le plus souvent une supposition.

Pire : se tromper en supposant est bon marché et paraît sûr. Une règle que personne ne comprend est une règle que quelqu'un finit par supprimer lors d'un rangement, et ce qu'elle empêchait revient.

Chaque règle porte donc ici à quoi elle sert et où on peut le vérifier. Onze des lignes de commentaire portent une date, douze portent une valeur mesurée. Ce sont les deux choses qui permettent à un lecteur futur de décider si la raison tient toujours.

Trois qui ne survivraient pas sans leur commentaire

Un code de langue qui ressemblait à une extension de script. Une règle bloquant les fichiers source oubliés opérait sur l'extension, et l'une d'elles était .pl — Perl. Les aperçus de modèles s'appellent 2900.pl.svg, où pl veut dire polonais. Tous les aperçus polonais se sont mis à répondre 403 alors que toutes les autres langues allaient bien. Le commentaire dit maintenant que pl est délibérément absent de la liste, pourquoi, et ce qui a été mesuré quel jour. Sans cela, la prochaine personne qui range la liste l'y remet.

Deux interrupteurs là où un seul semble suffire. Les fichiers précompressés ne doivent pas être compressés à nouveau en sortie. La configuration pose no-gzip, ce qui arrête l'un des deux compresseurs du serveur. L'autre recompressait le fichier fini alors que l'en-tête annonçait toujours gzip, et les navigateurs recevaient un contenu illisible. Le commentaire explique pourquoi les deux sont là, no-gzip et no-brotli, car retirer le second ressemble à du rangement.

Une règle d'interdiction qui est inversée. La règle qui bloque les copies de sauvegarde n'énumère pas d'extensions interdites. Elle demande si un nom de fichier contient une extension source qui n'est pas à la fin — et attrape ainsi les noms que personne n'a encore inventés. Le commentaire liste les cinq noms sur lesquels la version évidente s'est trompée, avec leurs codes de statut. Lisez la règle seule et elle paraît inutilement maligne ; lisez le commentaire et elle paraît être la seule chose qui marche.

La version générale

Les commentaires qui répètent le code ne valent rien et tout le monde le sait. Ce n'est pas ce que sont ceux-ci. Ils consignent ce que le code ne peut pas : ce qui a mal tourné, ce qui a été mesuré, quel jour, et quelle solution de rechange a été écartée.

Le test pour savoir si un commentaire vaut la peine d'être écrit est assez simple. Si la ligne au-dessus était supprimée par quelqu'un qui ne connaît pas l'histoire, quelque chose casserait-il en silence ? Si oui, écrivez l'histoire. Si non, n'écrivez rien.

Trois pour un n'est pas un objectif. C'est ce que ce test a donné dans un fichier où presque chaque ligne existe parce que quelque chose de précis a mal tourné.