Faraday: Запрос функции: явные определения методов для HTTP-глаголов

Привет, @dduugg , вместо того, чтобы явно определять методы, я бы рассмотрел удобное для документации решение.
Мы также используем определение метапрограммирования в соединении: https://github.com/lostisland/faraday/blob/master/lib/faraday/connection.rb#L195

Это хорошо сочетается с пунктами, которые вы упомянули выше?
Если это так, мы могли бы воспроизвести аналогичный фрагмент документации для модуля Faraday .

Привет, @iMacTia , спасибо за ответ. Не думаю, что проблему можно решить с помощью документации. Могу я попросить вас рассказать о сопротивлении явным определениям? Думаю, так будет лучше оформить дискуссию. Например, подход к документации, вероятно, столь же подробен (с учетом различных директив @!method & @!scope , в дополнение к коду method_missing ), чем семь однострочных явных определений переадресации. Предлагаю на Faraday . Но я не знаю, является ли это объяснением здесь (код читается гораздо больше, чем пишется, поэтому я думаю, что оптимизация для автора кода в любом случае ошибочна).

В основном есть 2 момента, которые ставят меня в тупик в связи с этим изменением.

• Я лично не думаю, что использование delegates является преимуществом только для автора кода. Я использую Ruby в течение многих лет и, как и другие, я оценил лаконичный синтаксис этого языка. Когда я читаю какой-то код и нахожу delegates я сразу понимаю, что это значит, и потенциально может сжать десятки строк кода всего в пару из них.
• Прокси-серверы HTTP-глаголов - не единственный пример Фарадея, где мы пользуемся преимуществами метапрограммирования, существует гораздо больше примеров, которые, скорее всего, страдают от той же проблемы, которую вы подняли здесь, но еще не были замечены. Согласие с этим изменением либо сделает исключение, либо создаст прецедент, чего я бы хотел избежать.

Но вместо того, чтобы сосредоточиться на моем сопротивлении этому изменению, я бы предпочел обсудить, какие преимущества мы пытаемся здесь представить. Я полностью понимаю проблему, которую вы описываете, и думаю, что мы должны попытаться ее решить, если это возможно!
Итак, если основная проблема здесь - совместимость с IDE / инструментами для предложений кода, автозаполнения и документации, то я просто предлагаю найти альтернативное решение, например комментарии к документации (мы уже довольно широко используем YARD).
И вы также правы, когда говорите, что это решение столь же многословно, хотя я бы сказал, что комментарий не повлияет на удобочитаемость так сильно, как список методов, и его легко узнать.

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

• Обнаруживаемость не исключает использования метапрограммирования (хотя в этом конкретном случае я думаю, что явные def s являются правильным решением), но это потребует замены подхода method_missing , как описано ранее.
• Я не уверен, что понимаю аргумент delegates . Похоже, что Фарадей не использует явных делегаторов при обработке методов HTTP-глагола. (Путаница в этом вопросе, вероятно, связана с запахом кода, что реализация методов HTTP-команды слишком сложна).
• Придется согласиться не согласиться с тем, что delegate и тому подобное - помощь автору кода. Я работаю с людьми, у которых есть несколько десятилетий коллективного опыта работы с рубинами, и мы не обнаружили здесь каких-либо преимуществ читабельности для этого подхода (даже без учета времени, потерянного на попытки изучить API с помощью pry, YARD, sorbet и solargraph. ). Возможно, стоит понаблюдать за попыткой рубистов впервые изучить этот API, по крайней мере, в этом конкретном вопросе.

Просто пытаюсь дать здесь честный (и, надеюсь, полезный) отзыв. Я все еще ценю время и усилия, потраченные на этот вклад в OSS.

Привет, спасибо за всю твою тяжелую работу над Фарадеем! Я знаю, что это старая проблема, но я склонен согласиться с тем, что обнаруживаемость - это небольшая проблема. Я работаю над промежуточным программным обеспечением и добавил этот раздел в свой README. Моя библиотека ориентирована на тех, кто раньше, возможно, не использовал Фарадея, поэтому я обязан все объяснить. Я скажу (несколько нерешительно), что разгадывать все было непросто.

@gurgeous Я согласен, что документация - это определенно то веб-сайт Фарадея ), но я не понимаю, как предложение в этом выпуске решит ваш конкретный вопрос.

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

Поэтому я думаю, что улучшенная документация (визуальная или в коде) - это способ решить эту проблему.
Но, может быть, мне здесь что-то не хватает или какой-то конкретный вариант использования, где лучшая документация не поможет?
Правильно ли я понимаю понятие «обнаруживаемость»?

Правильно ли я понимаю понятие «обнаруживаемость»?

Не в моем случае. Я ожидал, что смогу выполнить ls Faraday в pry , а затем $ Faraday.get и т. Д., Если я захочу погрузиться в конкретный метод. Я чувствую, что смог эффективно сделать это с любым другим драгоценным камнем, который я использовал, редко (если вообще когда-либо) нужно было переходить на страницу документации, следовательно, открывать этот тикет. (Это в дополнение к другим проблемам, упомянутым выше, таким как инструменты статического анализа не могут распознать код, использующий библиотеку.)

Еще раз спасибо, что выслушали нас.

Обожаю сайт Фарадея! Может быть, я могу отправить PR с несколькими предложениями? Рад помочь. Я думаю, что такие усилия всегда окупаются для новичков. Дайте мне знать, если вам будет интересно.

Что касается pry + ls Faraday , я тоже являюсь поклонником этого шаблона и широко его использую. Отказ от method_missing - неплохая идея. Ruby постепенно движется в этом направлении с появлением Ruby 3, языковых серверов, удаленного хранилища больших двоичных объектов и т. Д. Я думаю, что это вторично по отношению к документации.

@gurgeous Мы _are_ заинтересованы в документации Pull Requests, находим каталог docs/ с набором Gemfile (и README), который используется для публикации веб-сайта на страницах GitHub, которые мы используем. Если его использование неясно, процесс обновления веб-сайта, пожалуйста, также откройте проблему или PR для _that_.

Спасибо за заботу о пользователях Фарадея!

Обожаю сайт Фарадея! Может быть, я могу отправить PR с несколькими предложениями? Рад помочь. Я думаю, что такие усилия всегда окупаются для новичков. Дайте мне знать, если вам будет интересно.

@gurgeous абсолютно! Мы всегда рады помощи в улучшении документации или веб-сайта, поскольку вещи, очевидные для нас, сопровождающих, могут быть не столь очевидны для пользователей. К тому же мы действительно боремся со временем, и это часто требует затрат на документацию. На самом деле, документация будет в гораздо худшем положении , если бы не было @olleolleolle продолжения усилий 😄!

Что касается точки pry (cc @dduugg), я никогда ее не использовал, поэтому я, вероятно, не мог понять.
Я просто попробовал с вашей дополнительной информацией и заметил, что ls Faraday::Connection действительно показывает как динамически сгенерированные, так и делегированные методы 🙌.
Итак, мое первоначальное понимание того, что мы не можем использовать такого рода «магию» Ruby, было неправильным, и на самом деле единственным ограничением является использование missing_method .

Что мне не очень понравилось, так это введение явных методов, таких как следующие:

def self.get(...)
  ...
end

def self.post(...)
  ...
end

# ... and so on ...

Но если мы сможем исправить обнаружение pry , добавив динамические определения или делегирования в основной модуль Faraday , то с этим все будет в порядке. Извините, что не получил с первого раза!

Не беспокойтесь о временных ограничениях. Никогда не расстраивайтесь из-за того, что вы сопровождаете ПО с открытым исходным кодом! Мы ценим ваши усилия, несмотря ни на что. Я тоже там был ...

Я начну обсуждение re: docs, чтобы убедиться, что мы находимся на одной странице.

@iMacTia Как пользователь узнает, что нужно заглянуть в Faraday::Connection ? С тех пор я переключился на HTTP-гем с обнаруживаемым API, но я быстро взглянул на https://lostisland.github.io/faraday/usage/, и ни один из примеров кода не использует его явно (хотя последний делает это неявно). В примерах в основном используются статические методы для Faraday , но они не встречаются в pry. Я не знаю ни одного другого драгоценного камня, который использовал бы этот подход, и я все еще считаю, что это антипаттерн.

Спасибо, как всегда, за то, что выслушали меня.