Вторая реализация это обещание, что две среды отвечают на один вопрос. Большинство портов ломают это обещание в первый месяц, тихо, и ущерб виден как две панели, которые расходятся в числах. Перенос библиотеки это в основном работа по сохранению совпадения, и мне её сделали пять правил.
Код: ReadSightRS, лицензия MIT.
Каноническая реализация написана на PHP. Крейт на Rust это побайтно точный порт, и те же правила применились к версиям на Python и Node.
Правило 1: ответ принадлежит одной реализации
Библиотека на PHP решает, что значит формула. Каждый другой язык её воспроизводит, включая округление и включая крайний случай, когда в тексте нет предложений.
Соблазн в том, чтобы улучшить порт: взять коэффициент получше, поправить округление, которое выглядит неверным. Сначала это правится в канонической версии, потом пересобираются векторы. Порт, который тихо улучшает оригинал, это форк с проблемой совместимости.
Правило кажется очевидным, пока в порте не появляется свой пользователь. Тогда просьба «поправьте у нас» звучит разумно, а ответ «сначала в PHP» требует объяснить, что улучшение в одном языке ломает сравнение между языками.
Правило 2: векторы генерируют, а не пишут
Эталонные векторы приходят из PHP-библиотеки, а не из порта. Они покрывают список поддерживаемых формул на язык, метрики analyze, каждую применимую формулу со своими inputs и повекторные слоги, сравнение с допуском 1e-9.
Написанные руками ожидания проверяют, что думал автор. Сгенерированные векторы проверяют, что делает оригинал, и только это порт обязан повторить.
Правило 3: приблизительность описана на месте применения
Счёт слогов по шаблонам TeX точен в точках переноса и приблизителен в количестве. Это свойство алгоритма, а не дефект, и его место в README рядом с таблицей режимов.
Четыре славянских языка идут на эвристике. Человек, который прочитал таблицу, знает, почему «дыхание» считается как четыре; тот, кто не прочитал, заводит баг, на который мейнтейнер ответил десять раз.
Правило 4: говорить идиомами языка, держать смысл
ReadSight::new() в Rust возвращает Result, score() возвращает Result<FormulaResult, Error>, пустой ввод это Error::EmptyText. Python поднимает исключение с тем же смыслом, JavaScript бросает.
Идиомы меняют форму вызова и никогда не меняют число, которое вернулось. Порт, который отдаёт ноль вместо ошибки, проще написать и опаснее использовать в пакетном прогоне.
Правило 5: исполняемая документация считается тестом
Примеры на Rust в README компилируются и запускаются через cargo test. Девяносто интеграционных тестов покрывают совпадение, перенесённые юнит-тесты и дымовой прогон, который собирает каждый язык и вызывает каждую поддерживаемую формулу.
README, который компилируется, не может разойтись с API. README, который только текст, расходится на первом переименовании, и первым это замечает пользователь, вставивший сломанный пример.
Чему учит третий порт
К третьему языку картина ясна: общая часть это данные и векторы, а каждый порт тонкий вокруг них. Rust вкладывает данные в бинарник, Python кеширует скомпилированные шаблоны в системном каталоге, Node возит их в пакете.
Это и есть полезный итог упражнения. Интересная работа ушла в одну каноническую реализацию и один набор векторов, остальное это адаптация, а адаптация дешева, когда определение правильного не обсуждается.
Где это заканчивается
Совпадение это функция, которую пользователь не видит. Оно держит сравнение двух документов после того, как конвейер под ними переписали, и оно незаметно до того дня, когда его нет.
Крейт выходит под MIT, #![forbid(unsafe_code)], а векторы лежат в репозитории, чтобы четвёртый порт начинался с определения, а не с догадки.
Чек-лист порта проверяйте на каждом шаге: тесты должны падать до правки и проходить после.
Рядом: библиотека читаемости о канонической библиотеке на PHP и читаемость в Node о порте, с которого началась эта серия.