Коментуючи регулярні вирази

Чи є загальні практики коментування регулярних виразів: вбудовані коментарі, що стосуються різної частини RegEx, або загальний коментар для всіх виразів?

На мою думку, хорошою практикою є стисло викладати в коментарях, що таке загальна ідея регулярного виразу. Це економить іншим розробникам (а іноді і самому) клопоту з копіювання вставляти регулярний вираз у аналізаторі, як RegExr , тільки щоб зрозуміти, що він робить.

Це дещо відповідна мова, але мова не вказана у питанні.

Книга "Занурись у Python" пропонує реалізувати коментарі, використовуючи багатослівні регулярні вирази :

Python дозволяє зробити це за допомогою багатослівних регулярних виразів. Багатослівний регулярний вираз відрізняється від компактного регулярного виразу двома способами:

• Пробіли ігноруються. Пробіли, вкладки та повернення каретки не збігаються як пробіли, вкладки та повернення каретки. Вони зовсім не відповідають. (Якщо ви хочете зіставити пробіл у багатослівному регулярному виразі, вам потрібно буде уникнути цього, поставивши перед ним зворотну косу рису.)
• Коментарі ігноруються. Коментар у багатослівному регулярному виразі - це як коментар у коді Python: він починається з #символу та йде до кінця рядка. У цьому випадку це коментар у багаторядковому рядку замість вашого вихідного коду, але він працює аналогічно.

Приклад:

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

Джерело та додаткові подробиці тут

Цей метод має невеликий недолік, що абонент повинен знати, що шаблон написаний у багатослівному форматі та викликати його відповідно.

Як правило, я напишу регулярний вираз і не пояснюю окремі фрагменти регулярного виразу, а радше, в чому його мета. Це те, що і чому. Це трохи схоже на запитання "Як мають виглядати мої коментарі?" на який можна сказати: " Не пишіть, що робить код, пишіть, чому код робить те, що він робить "

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

Якщо ви не намагаєтесь когось навчити реджексам за допомогою коментарів у коді, я не думаю пояснювати, що робитиме кожен окремий твір. Працюючи з іншими програмістами, можна сміливо припускати, що хтось би знав щось як глобальні регулярні вирази.

Я думаю, це насправді залежить від того, як ви збираєте регекс. Взагалі кажучи, я думаю, що було б поганою ідеєю розміщувати коментарі в самому рядку регулярних виразів (наскільки я не знаю в більшості сценаріїв). Якщо вам дійсно потрібно коментувати конкретні частини регулярного виразу (ви намагаєтесь когось навчити?), То розбийте кожен фрагмент на окремі рядки на власні рядки та коментуйте кожен рядок, використовуючи звичайний процес коментування для вашої мови програмування. В іншому випадку відповідь pleinolijf досить хороша.

приклад:

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

Зазвичай я визначаю константу рядка, назва якої описує загальну мету регулярного виразу.

Наприклад:

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

Ви можете додати коментар вище цієї константи, щоб дати йому опис, але зазвичай самої постійної назви має бути достатньо.

У деяких сценаріях розробники можуть використовувати регулярні вирази для відповідності тексту поза їх типовим доменом. Оригінальні розробники, можливо, пройшли безліч ітерацій, захоплюючи різні крайові випадки, які, можливо, були виявлені лише через цей ітераційний процес. Таким чином, наступні розробники можуть не знати про багато кращих випадків, з якими мали справу з оригінальними розробниками, навіть якщо вони знають про загальний випадок.

У таких випадках, можливо, варто задокументувати приклади змін. Розташування цієї документації може змінюватися залежно від кількості (наприклад, необов'язково в коді).

Один із способів наблизитись до цього - припустити, що майбутні розробники матимуть лише базові знання, як-от як працюють регулярні вирази, але не будь-які знання, які ви (1) мали до розробки регулярних виразів, які не обов'язково були б відомі майбутні розробники або (2) знання, які ви отримали під час розробки (наприклад, крайові випадки, які були виявлені).

Наприклад, якщо під час розробки ви говорите щось на кшталт "О, я не знав, що X може прийняти таку форму", тоді це варто документувати (і, можливо, та частина регексу, яка обробляє цю варіацію).

До коментарів слід додати корисну інформацію, яка не очевидна з коду.

1. Спростіть зрозуміти, що вираз повинен робити на рівні вимог, або в самому коді, або в коментарі. Який задум стоїть за цим виразом, це перевірити електронну адресу або вибрати канадські номери телефонів.
2. Спростіть зрозуміти, чим саме є вираз, тобто те, що вираження оцінює. Спочатку спробуйте це зрозуміти, розділивши вираз, якщо ви спочатку перевірите всі дефіси, потім видаліть усі числа, а потім зробіть вираз із двох частин зі змінними, що містять посередницькі значення, це полегшить читання, і читач буде здатний переходити через вашу логіку покроково. (Є відомий варіант відповіді на запитання щодо SE, де хтось намагається розшифрувати старий код, який передбачає маніпуляцію бітом '>>' та з'ясувати, чи встановлені певні прапори, де відповідь не тільки визначає, що дійсно робить код, але і як автор питання повинен іти про деконструкцію такого коду в майбутньому, що саме я намагаюся описати, але можу "

Є кілька додатків, які потребують кожного останнього циклу, якщо ви співставляєте масивні масиви даних, то, можливо, є кращий спосіб, можливо, ні, але для більшості речей додатковий час виконання не так вже й багато.

І пам’ятайте, що наступною людиною, яка наткнеться на ваш код і виправить помилку, ви можете стати через півроку, і немає жодного способу ви пам’ятати, що це мало робити.

Витягніть RegEx з окремого класу в a зі змістовною назвою. Тоді я б документував код за допомогою автоматизованих тестів.

Це забезпечить

• Те, що код насправді працює - також для кутових справ
• Слідкуйте за тим, щоб швидке «виправлення» не викликало багато кутових справ
• Може документувати оптимізації, коли зворотне відстеження вимкнено

Природно, у вашому класі може розміститися кілька регулярних виразів.