Comentando expresiones regulares

¿Existen prácticas comunes para comentar las expresiones regulares: comentarios en línea que hacen referencia a diferentes partes de RegEx o comentarios generales para todas las expresiones?

En mi opinión, una buena práctica es establecer de manera concisa en los comentarios cuál es la idea general de la expresión regular. Esto ahorra otros desarrolladores (o, a veces usted mismo) la molestia de copiar y pegar la expresión regular en un programa de análisis como RegExr , sólo para entender lo que hace.

Esta es una respuesta específica del idioma, pero no se indica ningún idioma en la pregunta.

El libro "Sumérgete en Python" sugiere implementar comentarios usando expresiones regulares verbosas :

Python le permite hacer esto con algo llamado expresiones regulares detalladas. Una expresión regular detallada es diferente de una expresión regular compacta de dos maneras:

• El espacio en blanco se ignora. Los espacios, las pestañas y los retornos de carro no coinciden como espacios, pestañas y retornos de carro. No están igualados en absoluto. (Si desea hacer coincidir un espacio en una expresión regular detallada, tendrá que escapar colocando una barra invertida delante de él).
• Los comentarios son ignorados. Un comentario en una expresión regular detallada es como un comentario en el código de Python: comienza con un #carácter y continúa hasta el final de la línea. En este caso, es un comentario dentro de una cadena de varias líneas en lugar de dentro de su código fuente, pero funciona de la misma manera.

Ejemplo:

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

Fuente y más detalles aquí

Este método tiene una pequeña desventaja de que la persona que llama debe saber que el patrón está escrito en un formato detallado y llamarlo en consecuencia.

Por lo general, escribiré una expresión regular y no explicaré las piezas individuales de la expresión regular, sino más bien cuál es su propósito. Eso es lo que y por qué. Esto es un poco como preguntar "¿Cómo deberían ser mis comentarios?" a lo que uno diría " No escriba lo que está haciendo el código, escriba por qué el código está haciendo lo que hace "

// 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 menos que esté tratando de enseñarle a alguien sobre expresiones regulares a través de comentarios en código, no creo que explique qué hará cada pieza individual. Al trabajar con otros programadores, puede asumir con seguridad que uno conocería algo como expresiones regulares globales.

Supongo que realmente depende de cómo estés armando la expresión regular. En general, creo que sería una mala idea poner comentarios dentro de la cadena de expresiones regulares en sí (no es posible en la mayoría de los escenarios, que yo sepa). Si realmente necesita comentar partes específicas de una expresión regular (¿está tratando de enseñarle a alguien?), Divida cada fragmento en cadenas separadas en sus propias líneas y comente cada línea utilizando el proceso normal de comentarios para su lenguaje de programación. De lo contrario, la respuesta de pleinolijf es bastante buena.

ejemplo:

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

Por lo general, defino una constante de cadena cuyo nombre describe el propósito general de la expresión regular.

Por ejemplo:

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

Puede agregar un comentario sobre esta constante para darle una descripción, pero generalmente el nombre de la constante debería ser suficiente.

En algunos escenarios, los desarrolladores pueden estar utilizando expresiones regulares para hacer coincidir el texto fuera de su dominio típico. Los desarrolladores originales pueden haber pasado por muchas iteraciones capturando varios casos extremos que solo podrían haberse descubierto a través de ese proceso iterativo. Por lo tanto, los desarrolladores posteriores pueden no estar al tanto de muchos de los casos límite que los desarrolladores originales trataron, incluso si están al tanto del caso general.

En casos como estos, puede valer la pena documentar ejemplos de las variaciones. La ubicación de esta documentación puede variar según la cantidad (por ejemplo, no necesariamente en el código).

Una forma de abordarlo es asumir que los futuros desarrolladores solo tendrán conocimientos básicos, como el funcionamiento de las expresiones regulares, pero ningún conocimiento que usted (1) haya tenido antes del desarrollo de las expresiones regulares que no necesariamente serían conocidas por el futuros desarrolladores o (2) conocimiento que adquirió durante el desarrollo (por ejemplo, casos extremos que se descubrieron).

Por ejemplo, si durante el desarrollo dices algo como "Oh, no sabía que X podría tomar esta forma", entonces vale la pena documentar eso (y tal vez la parte de la expresión regular que maneja esa variación).

Los comentarios deben agregar información útil que no sea obvia en el código.

1. Facilite la comprensión de lo que se supone que debe hacer la expresión a nivel de requisitos, ya sea en el código mismo o en un comentario. ¿Cuál es la intención detrás de la expresión? ¿Es validar direcciones de correo electrónico o elegir números de teléfono canadienses?
2. Facilite la comprensión de lo que realmente está haciendo la expresión, es decir, a qué se evalúa la expresión. Primero intente aclarar dividiendo la expresión, si primero verifica todos los guiones, luego elimina todos los números y luego hace que una expresión de dos partes con variables que contengan los valores intermedios, será mucho más fácil de leer y el lector será capaz de atravesar su lógica paso a paso. (Hay una respuesta famosa a una pregunta sobre SE en la que alguien está tratando de descifrar algún código antiguo que implica la manipulación de bits '>>' y descubrir si ciertas banderas están establecidas donde la respuesta establece no solo lo que el código realmente hace sino cómo la hora de la pregunta debería consistir en deconstruir este tipo de código en el futuro, que es exactamente lo que estoy tratando de describir pero puedo '

Hay pocas aplicaciones que necesiten cada último ciclo, si está haciendo coincidir patrones con conjuntos de datos masivos, entonces quizás haya una mejor manera, tal vez no, pero para la mayoría de las cosas, el tiempo de ejecución adicional no es tan importante.

Y recuerde que la próxima persona en encontrar su código y corregir un error podría ser usted dentro de seis meses y no hay forma de que recuerde lo que se suponía que debía hacer.

Extraiga el RegEx en una clase separada en un con un nombre significativo. Luego documentaría el código con pruebas automatizadas.

Esto asegurará

• Que el código realmente funciona, también para casos de esquina
• Asegura que una "corrección de errores" rápida no arruine muchos casos de esquina
• Puede documentar optimizaciones donde el retroceso está deshabilitado

Naturalmente, su clase puede albergar varias expresiones regulares.