Commenter des expressions régulières


11

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?


2
Il y en a mais vous devez être plus précis. Par exemple, Bash prend en charge les commentaires en ligne et Python propose des expressions régulières verbeuses.
sakisk

6
Ma règle d'or pour les expressions régulières est: si vous avez besoin de commenter l'expression régulière, c'est trop compliqué.
zzzzBov

1
Et incluez toujours ce lien: regexcrossword.com
Kieveli

Je ne suis pas nécessairement d'accord que si vous devez le commenter, c'est trop compliqué. Une expression rationnelle compliquée peut encore vous faire économiser des tonnes de code impératif. Utilisez un bon nom de variable descriptive pour affecter l'expression régulière à. Si ce n'est toujours pas assez clair, utilisez un bref commentaire pour exprimer l' intention originale derrière l'expression régulière.
Craig

Réponses:


10

À 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.


2
RegExr se produira de toute façon, sauf si le développeur est un savant regex. Mais je suis d'accord pour fournir une description générale; c'est ce que je fais avec mes regex.
Robert Harvey

3
+1: Tout ce qui est plus détaillé finira par être un cours intensif en regex en tant que commentaire.
Matt

Cette réponse et les commentaires @zzzzBov ont du sens.
m0nhawk

1
Non seulement cela évite les tracas d'un examen fastidieux de l'expression régulière pour le comprendre, mais cela rend l'intention du programmeur d'origine claire, surtout compte tenu de la possibilité distincte que le programmeur d'origine se soit trompé l'expression régulière elle-même la première fois. Cela dit, dans de nombreux cas, attribuer l'expression régulière à un bon nom de variable peut être très utile pour fournir une documentation d'intention adéquate.
Craig

9

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.


2
Plutôt que de stocker le motif dans une variable, vous pouvez l'utiliser re.compileau point où vous définissez votre motif et ne stocker que l'objet résultant. De cette façon, les drapeaux de compilation de modèles (y compris re.VERBOSE) n'ont pas besoin d'être séparés du modèle lui-même.
John Bartholomew

Réponse vraiment utile, merci! Mais comment puis-je faire correspondre un #si j'utilise le drapeau verbeux? Soit dit en passant: les liens source semblent être en panne.
winklerrr

D'accord, il #peut donc être mis en correspondance littéralement à l'intérieur d'une classe de caractères: [#](source: docs.python.org/3/library/re.html#re.X )
winklerrr

8

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.


3
vous seriez surpris ...
Matt

6

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

4

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.


1
Une chose supplémentaire que j'aime dans cette réponse est que si elle est utilisée à plusieurs endroits, l'intention doit également être portée - sans oublier de la commenter.
J Trana

3

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).


2

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.


1

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.

En utilisant notre site, vous reconnaissez avoir lu et compris notre politique liée aux cookies et notre politique de confidentialité.
Licensed under cc by-sa 3.0 with attribution required.