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