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?
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?
Réponses:
À 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.
re.compile
au 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.
#
si j'utilise le drapeau verbeux? Soit dit en passant: les liens source semblent être en panne.
#
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 )
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.
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
Naturellement, votre classe peut héberger plusieurs expressions régulières.