Post Mortem к использованию библиотеки

[vkazanov]

Подвожу небольшие итоги к использованию библиотеки в качестве парсера для регулярных выражений. Комментарии на русском - так будет быстрей.

Для начала хочу отметить, что библиотека по существу очень полезна, я думаю ее использовать в следующем моем небольшом проекте. Более того, по результатам тех моих статей библиотекой заинтересовались некоторые мои хорошие знакомые из крупных международных компаний, и их оттолкнули те же проблемы, с которыми столкнулся я сам.

Опять же, по логике работы библиотеки у меня пока вопросов нет, их я задал еще когда писался код для регулярных выражений.

Однако несмотря на наличие времени и желания разобраться мне пришлось обратиться к вам за помощью в оформлении фазы кодогенерации и обработки ошибок. Отсюда следует проблема первая и основная: несмотря на наличие примеров документации, покрывающей основы использования, не хватает.

Чтение примеров и тестов здесь, конечно, помогает, но ограниченно.

Во-первых, вы не соблюдаете обычные для Питона соглашения по оформлению кода, то есть все примеры и код мне надо как переформатировать для включения в проект. В Питоне не принято нарушать pep8 и следующие за ним стилевые руководства, а любые нарушения сразу вызывают подозрения в непрофессионализме. Это, собственно, пришло замечание из австралийского офиса Гугла.

Во-вторых, в силу отсутствия документации не было возможности понять терминологию, которая используется в коде. Комментарии вида "вдохновлено тем-то и тем-то" ссылаются на относительно сложные и разнородные проекты/языки, то есть библиотека как бы не является самодостаточной: надо иметь представление о том, как такие вещи работают в Прологе, или Стратего, или еще где-то в третьем месте. Ничего сложного там нет, но как, к примеру, понять, что именно из этих проектов вы решили использовать? Какие термины переняли?

В-третьих, вы стараетесь держать код предельно компактным. Но библиотека занимает меньше 500 строк в сумме. Добавление docstrings к основным модулям/классам/методам/функциям бы сильно упростило чтение кода, нисколько ему не навредив. И совершенно бесплатно позволило бы генерировать документацию из кода при помощи, например, Sphinx.

В-четвертых, я уже не помню, когда последний раз видел либу на Питоне, которую нельзя было скачать из PyPi.

В-пятых, тесты могли бы здорово помощь в понимании работы кода. Обычно в проектах без документации (а это суровая реальность коммерческой разработки) тесты - первое место, где можно хоть как-то ознакомиться с внутренними API кода, но, к сожалению, я нашел только очень примитивные тесты для примеров, чего явно недостаточно как для тестирования, так и для ознакомления.

Ну, и наконец, неплохо бы оформить какой-нибудь туториал, который бы по шагам объяснял разработку какого-нибудь компилятора.

Буду рад помочь с решением перечисленных вопросов!

И еще раз спасибо за ваши комментарии и самое приятное открытие конца года - чатик в Телеграмме. :-)