Commenter des expressions régulières

Existe-t-il des pratiques courantes pour commenter les expressions régulières: commentaires en ligne faisant référence à différentes parties de RegEx ou commentaire général pour toutes les expressions?

À mon avis, une bonne pratique consiste à énoncer de manière concise dans les commentaires quelle est l'idée générale de l'expression régulière. Cela évite aux autres développeurs (ou parfois à vous-même) les tracas du copier-coller de l'expression régulière dans un analyseur comme RegExr , uniquement pour comprendre ce qu'il fait.

Il s'agit d'une réponse spécifique à une langue, mais aucune langue n'est indiquée dans la question.

Le livre "Dive Into Python" suggère d'implémenter des commentaires à l'aide d' expressions régulières verbeuses :

Python vous permet de le faire avec quelque chose appelé expressions régulières verbeuses. Une expression régulière verbeuse est différente d'une expression régulière compacte de deux manières:

• L'espace est ignoré. Les espaces, les tabulations et les retours chariot ne correspondent pas en tant qu'espaces, tabulations et retours chariot. Ils ne correspondent pas du tout. (Si vous voulez faire correspondre un espace dans une expression régulière verbeuse, vous devrez y échapper en mettant une barre oblique inverse devant.)
• Les commentaires sont ignorés. Un commentaire dans une expression régulière détaillée est comme un commentaire dans le code Python: il commence par un #caractère et va jusqu'à la fin de la ligne. Dans ce cas, il s'agit d'un commentaire dans une chaîne de plusieurs lignes plutôt que dans votre code source, mais cela fonctionne de la même manière.

Exemple:

>>> pattern = """
^                   # beginning of string
M{0,4}              # thousands - 0 to 4 M's
(CM|CD|D?C{0,3})    # hundreds - 900 (CM), 400 (CD), 0-300 (0 to 3 C's),
                    #            or 500-800 (D, followed by 0 to 3 C's)
(XC|XL|L?X{0,3})    # tens - 90 (XC), 40 (XL), 0-30 (0 to 3 X's),
                    #        or 50-80 (L, followed by 0 to 3 X's)
(IX|IV|V?I{0,3})    # ones - 9 (IX), 4 (IV), 0-3 (0 to 3 I's),
                    #        or 5-8 (V, followed by 0 to 3 I's)
$                   # end of string
"""
>>> re.search(pattern, 'M', re.VERBOSE)                1

Source et détails ici

Cette méthode présente un léger inconvénient: l'appelant doit savoir que le modèle est écrit dans un format détaillé et l'appeler en conséquence.

En règle générale, j'écrirai une expression régulière et je n'expliquerai pas les éléments individuels de l'expression régulière, mais plutôt son objectif. C'est ça et pourquoi. C'est un peu comme demander "A quoi devraient ressembler mes commentaires?" à laquelle on dirait " N'écrivez pas ce que fait le code, écrivez pourquoi le code fait ce qu'il fait "

// Strip the leading "?" and remove the query parameters "offset=<integer>" & "count=<integer> so we have a pattern of the request"          
var search = location.search.substring(1).replace(/offset=[0-9]+?&/g, "").replace(/count=[0-9]+?&/g, "");

À moins que vous n'essayiez d'enseigner à quelqu'un des expressions rationnelles via des commentaires dans le code, je ne pense pas expliquer ce que chaque morceau individuel fera. Lorsque vous travaillez avec d'autres programmeurs, vous pouvez supposer en toute sécurité que l'on connaît quelque chose en tant qu'expressions régulières globales.

Je suppose que cela dépend vraiment de la façon dont vous assemblez l'expression régulière. De manière générale, je pense que ce serait une mauvaise idée de mettre des commentaires dans la chaîne regex elle-même (pas possible dans la plupart des scénarios, pour autant que je sache). Si vous avez vraiment besoin de commenter des parties spécifiques d'une expression régulière (essayez-vous d'enseigner à quelqu'un?), Divisez chaque morceau en chaînes distinctes sur leurs propres lignes et commentez chaque ligne en utilisant le processus de commentaire normal pour votre langage de programmation. Sinon, la réponse de pleinolijf est plutôt bonne.

exemple:

string myregex = "\s" // Match any whitespace once
+ "\n"  // Match one newline character
+ "[a-zA-Z]";  // Match any letter

Je définis généralement une constante de chaîne dont le nom décrit l'objectif général de l'expression régulière.

Par exemple:

const string FloatingPointNumberPattern = @"[-+]?[0-9]*\.?[0-9]+";

Vous pouvez ajouter un commentaire au-dessus de cette constante pour lui donner une description, mais le nom de la constante elle-même devrait généralement suffire.

Dans certains scénarios, le ou les développeurs peuvent utiliser des expressions régulières pour faire correspondre le texte en dehors de leur domaine typique. Les développeurs d'origine peuvent avoir traversé de nombreuses itérations en capturant divers cas de bord qui n'auraient pu être découverts que par ce processus itératif. Ainsi, les développeurs ultérieurs peuvent ne pas être au courant de la plupart des cas marginaux traités par le (s) développeur (s) d'origine, même s'ils connaissent le cas général.

Dans de tels cas, il peut être utile de documenter des exemples de variations. L'emplacement de cette documentation peut varier en fonction du montant (par exemple, pas nécessairement dans le code).

Une façon de l'aborder est de supposer que les futurs développeurs n'auront que des connaissances de base, comme le fonctionnement des expressions régulières, mais pas aucune connaissance que vous non plus (1) aviez avant le développement des expressions régulières qui ne serait pas nécessairement connue du les futurs développeurs ou (2) les connaissances que vous avez acquises au cours du développement (par exemple, les cas de bord qui ont été découverts).

Par exemple, si pendant le développement vous dites quelque chose comme "Oh, je ne savais pas que X pouvait prendre cette forme", alors cela vaut la peine de le documenter (et peut-être la partie de l'expression rationnelle qui gère cette variation).

Les commentaires doivent ajouter des informations utiles qui ne sont pas évidentes dans le code.

1. Facilitez la compréhension de ce que l'expression est censée faire au niveau des exigences, soit dans le code lui-même, soit dans un commentaire. Quelle est l'intention derrière l'expression, est-ce pour valider les adresses électroniques ou choisir des numéros de téléphone canadiens.
2. Faites en sorte qu'il soit facile de comprendre ce que fait réellement l'expression, c'est-à-dire ce que l'expression évalue. Essayez d'abord de le clarifier en divisant l'expression, si vous vérifiez d'abord tous les traits d'union, puis supprimez tous les nombres, puis créez une expression en deux parties avec des variables contenant les valeurs intermédiaires, cela facilitera la lecture et le lecteur sera capable de parcourir votre logique une étape à la fois. (Il y a une réponse célèbre à une question sur SE où quelqu'un essaie de déchiffrer un ancien code qui implique une manipulation de bits '>>' et de savoir si certains indicateurs sont définis où la réponse indique non seulement ce que fait réellement le code mais comment l'autheure de la question devrait aller à propos de la déconstruction de ce type de code à l'avenir, c'est exactement ce que j'essaie de décrire, mais je peux '

Il y a peu d'applications qui ont besoin de chaque dernier cycle, si vous faites correspondre des modèles d'ensembles de données massifs, alors il y a peut-être une meilleure façon, peut-être pas, mais pour la plupart des choses, le temps d'exécution supplémentaire n'est pas si grave.

Et rappelez-vous que la prochaine personne qui rencontrera votre code et corrigera un bogue pourrait être vous dans six mois et il n'y a aucun moyen que vous vous souveniez de ce qu'il était censé faire.

Extrayez le RegEx dans une classe distincte en un avec un nom significatif. Ensuite, je documentais le code avec des tests automatisés.

Cela garantira

• Que le code fonctionne réellement - également pour les cas d'angle
• Garantit qu'un "bugfix" rapide ne gâche pas beaucoup de cas d'angle
• Peut documenter des optimisations lorsque le retour arrière est désactivé

Naturellement, votre classe peut héberger plusieurs expressions régulières.