Существуют ли общие практики для комментирования регулярных выражений: встроенные комментарии, ссылающиеся на различные части RegEx, или общие комментарии для всех выражений?
documentation
coding-style
comments
m0nhawk
источник
источник
Ответы:
На мой взгляд, хорошей практикой является кратко излагать в комментариях общую идею регулярного выражения. Это избавит других разработчиков (или иногда вас самих) от необходимости вставлять регулярные выражения в такой синтаксический анализатор, как RegExr , только для того, чтобы понять, что он делает.
источник
Это в некоторой степени зависит от языка, но в вопросе язык не указан.
Книга «Dive Into Python» предлагает реализовать комментарии с использованием подробных регулярных выражений :
Пример:
Источник и дальнейшие подробности здесь
Этот метод имеет небольшой недостаток: вызывающий должен знать, что шаблон написан в подробном формате, и вызывать его соответствующим образом.
источник
re.compile
в том месте, где вы определяете свой шаблон, и сохранять только полученный объект. Таким образом, флаги компиляции шаблона (включаяre.VERBOSE
) не нужно отделять от самого шаблона.#
если я использую подробный флаг? Кстати: ссылки на источник, кажется, не работает.#
может быть найдено буквально, когда внутри класса персонажа:[#]
(source: docs.python.org/3/library/re.html#re.X )Как правило, я напишу регулярное выражение и не объясню отдельные части регулярного выражения, а скорее, какова его цель. Вот что, что и почему. Это немного похоже на вопрос "Как должны выглядеть мои комментарии?" на что можно сказать: « Не пиши, что делает код, напиши, почему код делает то, что делает »
Если вы не пытаетесь научить кого-либо о регулярных выражениях с помощью комментариев в коде, я не думаю, что объясню, что будет делать каждый отдельный фрагмент. Работая с другими программистами, вы можете смело предполагать, что кто-то будет знать что-то вроде глобальных регулярных выражений.
источник
Я думаю, это действительно зависит от того, как вы соединяете регулярное выражение. Вообще говоря, я думаю, что было бы плохой идеей помещать комментарии внутри самой строки регулярного выражения (насколько я знаю, это невозможно в большинстве сценариев). Если вам действительно нужно комментировать определенные части регулярного выражения (вы пытаетесь кого-то научить?), То разбивайте каждый кусок на отдельные строки в своих строках и комментируйте каждую строку, используя обычный процесс комментирования для вашего языка программирования. В противном случае ответ Pleinolijf довольно хороший.
пример:
источник
Я обычно определяю строковую константу, имя которой описывает общую цель регулярного выражения.
Например:
Вы можете добавить комментарий над этой константой, чтобы дать ей описание, но обычно достаточно имени самой константы.
источник
В некоторых сценариях разработчик (-и) могут использовать регулярные выражения для сопоставления текста за пределами своей типичной области. Первоначальные разработчики, возможно, прошли много итераций, захватывая различные крайние случаи, которые могли быть обнаружены только в ходе этого итерационного процесса. Таким образом, последующие разработчики могут не знать о многих крайних случаях, с которыми сталкивались первоначальные разработчики, даже если они знают об общем случае.
В таких случаях может быть целесообразно задокументировать примеры вариантов. Расположение этой документации может варьироваться в зависимости от суммы (например, не обязательно в коде).
Один из подходов к этому - предположить, что будущие разработчики будут иметь только базовые знания, например, как работают регулярные выражения, но не знания, которые вы (1) имели до разработки регулярных выражений, которые не обязательно были бы известны будущие разработчики или (2) знания, которые вы получили во время разработки (например, крайние случаи, которые были обнаружены).
Например, если во время разработки вы скажете что-то вроде «О, я не знал, что X может принять эту форму», тогда стоит документировать это (и, возможно, ту часть регулярного выражения, которая обрабатывает этот вариант).
источник
Комментарии должны добавлять полезную информацию, которая не очевидна из кода.
Есть несколько приложений, которые нуждаются в каждом последнем цикле, если вы сопоставляете с образцом массивные наборы данных, то, возможно, есть лучший способ, а может и нет, но для большинства вещей дополнительное время выполнения не так уж важно.
И помните, что следующим человеком, который найдет ваш код и исправит ошибку, может быть вы через шесть месяцев, и вы никак не сможете вспомнить, что он должен был делать.
источник
Извлеките RegEx в отдельный класс с осмысленным именем. Затем я документировал код с помощью автоматических тестов.
Это обеспечит
Естественно, ваш класс может содержать несколько регулярных выражений.
источник