Перейти до вмісту
Leonidov.DEV

Бібліотека читабельності: 4 порти й один однаковий бал

Інженерія
Бібліотека читабельності: 4 порти й один однаковий бал

Один і той самий український абзац дав 11,2 у PHP і 11,9 у Python. Обидва числа виглядали правдоподібно, обидва пішли в дашборд клієнта, і помітили це лише на зустрічі, де два слайди не зійшлися.

Код: ReadSight, ліцензія MIT.

Так починається портування. Бібліотека читабельності, написана для PHP, переписується іншою мовою, бо переїхав конвеєр, і за пів року ніхто не може сказати, яка реалізація правильна.

Тепер моя бібліотека читабельності працює чотирма мовами й повертає однакові числа в усіх. Дорога туди була не про математику, а про домовленість, що означає «однакові».

Навіщо портувати

Підрахунок читабельності живе там, де живе текст. Сайту на PHP він потрібен у команді WP-CLI. Сервісу на Node в обробнику запиту. Конвеєру на Python до кроку з ембедингами. Задачі на Rust, бо пакетний прогін там швидший.

Викликати для цього сервіс означає мережевий перехід на сторінку, і сервіс стає залежністю для чистої арифметики над рядками.

Чотири пакети це PHP, Python, TypeScript і Rust, у кожного немає залежностей у рантаймі й дані мов лежать усередині.

Що розходиться під час переписування

Самі формули опубліковані й стабільні. Gunning Fog це фіксований вираз над словами, реченнями й складними словами. Неоднозначного в ньому немає.

Розходиться все навколо формули.

Підрахунок символів перший. mb_strlen у PHP і String.length у JavaScript рахують різне, тому слово з комбінованим наголосом це чотири символи в одному й два в іншому, а індекс Coleman-Liau читає символи на сто слів.

Округлення друге. Бал 11,25 округлюється до 11 в одній мові й до 11,3 в іншій, і дашборд, що порівнює дві системи, показує різницю, яка є артефактом форматування.

Розбиття на слова третє. Складене слово через дефіс це одне слово в одній реалізації й два в іншій, і це рухає середню довжину речення та всі бали разом із нею.

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

Як змусити чотири реалізації домовитися

Відповідь це спільний набір тестів, і він зайняв три ітерації.

Кожен випадок це текст, мова й формула з очікуваним значенням, зафіксованим на заданій точності. Кожен порт читає ту саму таблицю і валить збірку за розбіжності з нульовим допуском. Не «досить близько», бо близькість і є місце, де живе дрейф.

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

Еталон це не автоматично PHP. По кожному спірному випадку ми перевіряємо опубліковану формулу руками й вирішуємо, яка поведінка правильна, а потім приводимо до неї всі порти. Двічі це рішення було проти PHP.

Що в портів спільне

Один движок складів: шаблони переносів TeX за Frank M. Liang, застосовані на кожну мову, з тими самими списками винятків.

Один реєстр формул: 17 формул, із них п’ять працюють будь-якою мовою і дванадцять несуть опубліковані коефіцієнти. Кожна мова оголошує, які формули підтримує, тому англійська отримує дев’ять, а німецька вісім.

Один формат файлу даних, згенерований один раз і скопійований, тому виправлення коефіцієнта потрапляє в усі чотири пакети в одному релізі.

Чи варте це

Для однієї реалізації ні. Чотири реалізації однієї арифметики це рахунок на підтримку, який має сенс лише якщо альтернатива це мережева залежність у чотирьох різних конвеєрах.

Оплачуваним його робить набір тестів. Без нього чотири порти це чотири бібліотеки, які випадково носять одне ім’я. З ним зміна однією мовою падає на трьох інших до релізу, і дрейф, із якого почався проєкт, більше не повториться.

Дисципліна за цим та сама, що не дає проєкту згоріти: запиши специфікацію до коду, про що розбір відсутності специфікації. А коли порт живе у великій системі, важливий вибір меж, як у шести патернах архітектури.

Пакети: Packagist, PyPI, npm, crates.io.