Англійська для пояснення шаблонів регулярних виразів товаришам по команді

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

Ключовий словник

** Match ** — частина вхідного рядка, яка відповідає шаблону; опис того, що регулярний вираз « відповідає », є початковою точкою для будь- якого пояснення.

• “Ця модель відповідає будь- якому рядку, що починається з « IMG_ », за яким слідує точно шість цифр і суфікс файла.” *

** Група захоплення ** — частина шаблону у дужках, яка витягує певний підрядок зі збігу, на який пізніше буде посилатися за індексом або назвою.

• “Друга група захоплення витягує чотиризначний рік з рядка дати, який ми використовуємо для впорядкування файлів за роком.” *

** Якоря ** — символ, на зразок ^ або $, який обмежує, де у рядку збіг має починатися або закінчуватися, замість того, щоб збігатися з будь- яким місцем у ньому. “Ми зафіксуємо шаблон з ^ і $, щоб він відповідав всьому рядку, а не лише підрядку десь посередині.”

** Жадний проти лінивого збігу ** — жадібний збіг використовує якомога більше вхідних даних перед поверненням назад; лінивий збіг використовує якомога менше; ця різниця має значення, якщо шаблон може збігатися з декількома довжинами. “Ми переключилися з жадібного на ліниве збігання тут — .*? замість .* — тому що жадібна версія збігалася до останнього </div> у файлі замість того, щоб зупинитися на найближчому.”

** Країнний регістр (у регулярному виразі) ** — вхідний сигнал, який технічно задовольняє або не задовольняє шаблон у спосіб, який автор, можливо, не передбачав, часто є джерелом незначних помилок. “Один крайній випадок, який не обробляється цим шаблоном: листи зі знаком плюс, наприклад user+tag@example.com, які є коректними, але відкидаються.”

Звичайні фрази

• «Цей шаблон відповідає [опис], але не обробляє [країнний регістр]»
• «Група захоплення тут витягує [спеціальне значення] для пізнішого використання»
• «Ми зафіксували шаблон так, щоб він відповідав всьому рядку, а не підрядку.»
• «Це має бути ліниво, не жадібно, або це перебільшує»
• «Я перевірив це проти [список прикладних вхідних даних], щоб підтвердити граничні випадки»

Приклади висловлювань

Пояснення шаблону у коментарі коду, простим англійським перед самим формальним виразом:

• ”// Відповідає семантичній версії, наприклад, « 1. 4. 2 » або « 1. 4. 2- beta. 1 ». // Групи захоплення: 1 = головна, 2 = неголовна, 3 = латка, 4 = необов’ язковий міток передвипуску. const versionPattern = / ^ (\ d+). (\ d+). (\ d+)(?: - - [a- z0- 9.] +)? $ /;” *

Опис виправлення у повідомленні про помилку після виявлення вади:

• “У старому шаблоні між мітками використовувалися .*, що є жадібним і відповідає декільком елементам, якщо вхідний текст містив більше одного мітка на рядок. Перемикнуто на .*? (лінивець), тому він зупиняється на найближчому закриваючому тег замість останнього.”*

Позначити обмеження явно, замість того, щоб дозволити переглядачеві виявити його пізніше:

• “Зауваження: цей шаблон перевіряє більшість форматів електронної пошти, але не приймає + у локальній частині, отже адреси типу user+newsletter@example.com буде відхилено. Якщо нам потрібно підтримувати це, я можу оновити клас символів перед об’єднанням.”*

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

Професійні поради

• Завжди додавайте коментар ** простою англійською мовою ** над нетривіальним регулярним виразом — описуйте, що він відповідає і що витягує кожна група захоплення, оскільки синтаксис регулярного виразу сам по собі не повідомляє про намір.
• Явно вкажіть, які ** краї випадки обробляються і не обробляються ** — це одне речення запобігає багатьом «чому це не вловило X» помилок вниз по лінії.
• Використовуйте терміни « жадібний » і « лінивий », коли пояснюєте виправлення — вони описують реальний, специфічний механізм, і переглядачі, знайомі з регулярними виразами, відразу зрозуміють клас помилок, який ви описуєте.
• Коли ви просите когось пояснити свій регулярний вираз у рецензії, сформулюйте це як бажання ** підтвердити спільне розуміння **, не ставлячи під сумнів їх компетентність — читабельність регулярного виразу є відомою, поширеною проблемою, а не особистою помилкою.
• Перелічте декілька конкретних прикладів вхідних даних, які ви перевірили (включаючи ті, що повинні зазнати невдачі) в описі PR — це переконливіше, ніж сказати «Я перевірив це»

Практичні вправи

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

Навигація Nuance: Рефінансування Ваших Regex пояснень для не-рідних мовців

Ефективне обмінювання складними технічними концепціями, такими як регулярні вирази, є ключовим для співпраці і підтримки. Однак, простого зауваження «Використовувати цей регулярний вираз» недостатньо - особливо при роботі з членами команди, які не можуть бути рідними англійськими носієм або не повністю усвідомили нюанси формального технічного письма. Це точність, ясність і передбачення потенційних непорозумінь. Добре зроблене пояснення піднімає просту інструкцію до цінного шматка знань, на який можна посилатися і розуміти пізніше. Не обмежуйтеся лише переліком символів; розгляньте * чому * ви їх використовуєте і як вони пов’ язані з загальною метою.

Однією з найпоширеніших помилок є припущення, що всі розуміють жаргонні вирази, такі як « клас символів » або « зворотне посилання ». Замість того, щоб сказати: « У формальному виразі використано клас символів », спробуйте сформулювати його так: « Цей формальний вираз відповідає шаблонам за допомогою групування символів разом — уявіть, що ви визначаєте категорії для пошуку ». Аналогічно, замість того, щоб сказати: « Ми використовуємо зворотне посилання для отримання відповідної групи », подумайте про наступне: « Цей формальний вираз запам’ ятовує те, що було знайдено раніше, і використовує цю інформацію у пошуку, що дозволяє нам ефективно видобувати певні частини вхідних даних. » Спрямуйте увагу на * ефект * формального виразу, а не занурюйтеся у технічні деталі.

Важливо, коли ви пишете коментарі до коду або описи PR, пов’ язані з шаблонами регулярних виразів, приймайте розмовний, але формальний тон. Уникайте надмірно спрощених пояснень — носії англійської мови все ще можуть неправильно зрозуміти, якщо мова занадто проста. Пояснення слід вписувати у контекст самого коду. Наприклад, замість « Цей регулярний вираз знаходить адреси електронної пошти », спробуйте: « Частина [a-zA-Z0-9._%+-]+ цього формального виразу відповідає частині адреси електронної пошти, що містить ім’ я користувача, що забезпечує правильну перевірку введення користувача ». Пам’ ятайте, що навіть здавалося б прості пояснення потребують деяких пояснень — пояснення того, * чому * ви обрала певний шаблон або підхід, додасть значної цінності.

Нарешті, пам’ятайте про потенційні культурні відмінності в стилях спілкування. Деякі культури можуть віддавати перевагу більш прямим інструкціям, в той час як інші цінують більший контекст і пояснення. Спостереження за вподобаннями вашої команди і відповідне адаптування вашого стилю може значно поліпшити розуміння і зменшити потребу у повторних поясненнях. Врешті-решт, ефективні пояснення регулярних виразів стосуються сприяння спільному розумінню - забезпечення того, щоб кожен в команді був вирівняний з тим, як використовуються ці потужні інструменти.