Один і той самий український абзац дав 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 формул, із них п’ять працюють будь-якою мовою і дванадцять несуть опубліковані коефіцієнти. Кожна мова оголошує, які формули підтримує, тому англійська отримує дев’ять, а німецька вісім.
Один формат файлу даних, згенерований один раз і скопійований, тому виправлення коефіцієнта потрапляє в усі чотири пакети в одному релізі.
Чи варте це
Для однієї реалізації ні. Чотири реалізації однієї арифметики це рахунок на підтримку, який має сенс лише якщо альтернатива це мережева залежність у чотирьох різних конвеєрах.
Оплачуваним його робить набір тестів. Без нього чотири порти це чотири бібліотеки, які випадково носять одне ім’я. З ним зміна однією мовою падає на трьох інших до релізу, і дрейф, із якого почався проєкт, більше не повториться.
Дисципліна за цим та сама, що не дає проєкту згоріти: запиши специфікацію до коду, про що розбір відсутності специфікації. А коли порт живе у великій системі, важливий вибір меж, як у шести патернах архітектури.