Commentando le espressioni regolari

A mio avviso, una buona pratica è di affermare concisamente nei commenti qual è l'idea generale dell'espressione regolare. Questo salva gli altri sviluppatori (o talvolta te stesso) il fastidio di copiare e incollare la regex in un parser come RegExr , solo per capire cosa fa .

Tipicamente, scriverò una regex e non spiegherò i singoli pezzi della regex, ma piuttosto quale sia lo scopo. Questo è ciò che e perché. Questo è un po 'come chiedere "Come dovrebbero apparire i miei commenti?" a cui uno direbbe " Non scrivere ciò che sta facendo il codice, scrivi perché il codice sta facendo quello che fa "

// 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, "");

A meno che tu non stia cercando di insegnare a qualcuno delle regex tramite commenti nel codice, non penso che spieghi cosa farà ogni singolo pezzo. Quando si lavora con altri programmatori, si può presumere che si possa sapere qualcosa come espressioni regolari globali.

Penso che dipenda davvero da come stai mettendo insieme la regex. In generale, penso che sarebbe una cattiva idea inserire i commenti all'interno della stringa regex stessa (non è possibile nella maggior parte degli scenari, per quanto ne so). Se hai davvero bisogno di commentare parti specifiche di un'espressione regolare (stai cercando di insegnare a qualcuno?), Quindi spezza ogni chunk in stringhe separate sulle loro linee e commenta ogni riga usando il normale processo di commento per il tuo linguaggio di programmazione. Altrimenti, la risposta di pleinolijf è piuttosto buona.

Esempio:

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

Questa è in qualche modo una risposta specifica per la lingua, ma nella domanda non è indicata alcuna lingua.

Il libro "Dive Into Python" suggerisce l'implementazione dei commenti usando espressioni verbose regolari :

Python allows you to do this with something called verbose regular expressions. A verbose regular expression is different from a compact regular expression in two ways:

• Whitespace is ignored. Spaces, tabs, and carriage returns are not matched as spaces, tabs, and carriage returns. They're not matched at all. (If you want to match a space in a verbose regular expression, you'll need to escape it by putting a backslash in front of it.)
• Comments are ignored. A comment in a verbose regular expression is just like a comment in Python code: it starts with a # character and goes until the end of the line. In this case it's a comment within a multi-line string instead of within your source code, but it works the same way.

Esempio:

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

Fonte e ulteriori dettagli qui

Questo metodo ha un leggero svantaggio che il chiamante deve sapere che il modello è scritto in un formato dettagliato e chiamarlo di conseguenza.

In genere definisco una costante di stringa il cui nome descrive lo scopo generale dell'espressione regolare.

Ad esempio:

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

Potresti aggiungere un commento sopra questa costante per fornirgli una descrizione, ma in genere il nome costante dovrebbe essere sufficiente.

I commenti dovrebbero aggiungere informazioni utili che non sono ovvie dal codice.

1. Semplifica la comprensione di cosa deve fare l'espressione a un livello di requisiti, nel codice stesso o in un commento. Qual è l'intento dietro l'espressione, è quello di convalidare gli indirizzi email o scegliere i numeri di telefono canadesi.
2. Semplifica la comprensione di ciò che l'espressione sta effettivamente facendo, cioè ciò che l'espressione valuta. Prima prova a chiarire suddividendo l'espressione, se prima controlli tutti i trattini allora rimuovi tutti i numeri poi fai un'espressione in due parti con le variabili che contengono i valori dell'intermediario, renderà molto più facile leggere e il lettore sarà in grado di attraversare la tua logica un passo alla volta. (C'è una famosa risposta a una domanda su SE in cui qualcuno sta cercando di decifrare un vecchio codice che implica la manipolazione dei bit "> >" e scoprire se alcune bandiere sono impostate dove la risposta non stabilisce solo ciò che il codice fa davvero ma come dovrebbe essere l'autenticità della domanda a decostruire questo tipo di codice nel futuro che è esattamente quello che sto cercando di descrivere ma non riesco a trovare la domanda a cui collegarmi)

Ci sono poche applicazioni che hanno bisogno di un ultimo ciclo, se ci sono pattern che corrispondono a set di dati massivi allora forse c'è un modo migliore, forse no, ma per la maggior parte delle cose il tempo di esecuzione extra non è un grosso problema.

E ricorda che la prossima persona a scoprire il tuo codice e correggere un bug potrebbe essere tra sei mesi e non c'è modo di ricordare quello che avrebbe dovuto fare.

Estrai la RegEx in una classe separata in una con un nome significativo. Quindi documenterei il codice con test automatici.

Ciò garantirà

• Il codice funziona effettivamente - anche per i casi d'angolo
• Assicura che una rapida "correzione" non rovini molti casi d'angolo
• Può documentare le ottimizzazioni in cui il backtracking è disabilitato

Naturalmente, la tua classe potrebbe ospitare diverse espressioni regolari.