Faraday: Permintaan Fitur: def metode eksplisit untuk kata kerja HTTP

Hai @dduugg , daripada mendefinisikan metode secara eksplisit, saya akan menjelajahi solusi yang ramah dokumentasi.
Kami juga menggunakan definisi pemrograman meta dalam koneksi: https://github.com/lostisland/faraday/blob/master/lib/faraday/connection.rb#L195

Apakah itu bekerja dengan baik dengan poin-poin yang Anda sebutkan di atas?
Jika demikian, kami juga dapat mereplikasi cuplikan dokumentasi serupa untuk modul Faraday .

Hai @iMacTia , terima kasih atas jawabannya. Saya tidak berpikir masalahnya dapat diselesaikan dengan dokumentasi. Bisakah saya menyusahkan Anda untuk menguraikan penolakan terhadap definisi eksplisit? Saya pikir itu akan lebih baik membingkai diskusi. Misalnya, pendekatan dokumentasi kemungkinan sama verbose (menghitung berbagai @!method & @!scope direktif, selain kode method_missing ) daripada tujuh defs penerusan eksplisit satu baris Saya menyarankan pada Faraday . Tapi saya tidak tahu apakah itu alasannya di sini (kode dibaca lebih banyak daripada yang tertulis, jadi saya pikir mengoptimalkan penulis kode adalah kesalahan).

Terutama ada 2 poin yang menempatkan saya di pagar dengan perubahan ini.

• Saya pribadi tidak berpikir menggunakan delegates adalah keuntungan hanya untuk penulis kode. Saya telah menggunakan Ruby selama bertahun-tahun sekarang dan seperti orang lain saya mulai menghargai sintaks singkat bahasa ini. Ketika saya membaca beberapa kode dan saya menemukan delegates saya langsung tahu apa artinya dan berpotensi menyingkat puluhan baris kode menjadi hanya beberapa dari mereka.
• Proksi kata kerja HTTP bukan satu-satunya contoh di Faraday di mana kami memanfaatkan metaprogramming, ada banyak lagi contoh, yang kemungkinan besar mengalami masalah yang sama dengan yang Anda angkat di sini, tetapi belum diperhatikan. Menyetujui perubahan ini akan membuat pengecualian atau membuat preseden, kedua hal yang ingin saya hindari.

Tetapi daripada berfokus pada penolakan saya terhadap perubahan ini, saya lebih suka membahas tentang keuntungan seperti apa yang kami coba perkenalkan di sini. Saya benar-benar memahami masalah yang Anda gambarkan dan saya benar-benar berpikir kita harus mencoba menyelesaikannya jika memungkinkan!
Jadi jika masalah utama di sini adalah kompatibilitas dengan IDE/alat untuk saran kode, pelengkapan otomatis, dan dokumentasi, maka saya hanya mengusulkan untuk mencari solusi alternatif seperti komentar dokumentasi (kami sudah menggunakan YARD cukup luas).
Dan Anda juga benar ketika Anda mengatakan solusi ini sama bertele-tele, meskipun saya berpendapat bahwa komentar tidak akan memengaruhi keterbacaan sebanyak daftar metode dan mudah dikenali.

Hai @iMacTia , terima kasih atas balasan Anda. Kami telah beralih ke perpustakaan lain dengan kemampuan penemuan dan dukungan alat API yang lebih baik, tetapi saya akan membagikan pemikiran saya jika Anda menganggapnya berguna.

• Discoverability tidak menghalangi penggunaan metaprogramming (meskipun dalam kasus khusus ini saya pikir eksplisit def s adalah cara untuk pergi), tetapi akan membutuhkan penggantian method_missing pendekatan, seperti yang dijelaskan sebelumnya.
• Saya tidak yakin saya mengerti argumen delegates . Faraday tampaknya tidak menggunakan delegator eksplisit dalam menangani metode kata kerja HTTP. (Kebingungan dalam hal ini mungkin adalah bau kode bahwa penerapan metode kata kerja HTTP terlalu rumit).
• Kita harus setuju untuk tidak setuju bahwa delegate dan sejenisnya adalah bantuan untuk penulis kode. Saya bekerja dengan orang-orang dengan beberapa dekade pengalaman ruby ​​kolektif, dan kami belum menemukan manfaat keterbacaan untuk pendekatan di sini (bahkan mengabaikan waktu yang hilang untuk mencoba menjelajahi API melalui pry, YARD, sorbet, dan solargraph ). Mungkin bermanfaat untuk menonton upaya rubyist untuk menjelajahi API ini untuk pertama kalinya, setidaknya pada titik spesifik ini.

Hanya mencoba memberikan umpan balik yang jujur ​​(dan semoga bermanfaat) di sini. Saya masih menghargai waktu dan usaha atas kontribusi ini untuk OSS.

Hei, terima kasih atas semua kerja kerasmu di Faraday! Saya tahu ini adalah masalah lama, tetapi saya cenderung setuju bahwa kemampuan untuk ditemukan adalah sedikit masalah. Saya sedang mengerjakan beberapa middleware dan saya menambahkan bagian ini ke README. Perpustakaan saya ditujukan untuk seseorang yang mungkin belum pernah menggunakan Faraday sebelumnya, jadi saya berkewajiban untuk menjelaskan berbagai hal. Saya akan mengatakan (agak ragu-ragu) bahwa tidak mudah untuk memecahkan teka-teki.

@gurgeous Saya setuju dokumentasi jelas merupakan bagian depan di mana kami dapat melakukan pekerjaan yang lebih baik (walaupun kami mulai menangani ini dengan meluncurkan Situs Web Faraday ), tetapi saya tidak melihat bagaimana saran dalam masalah ini akan menyelesaikan poin spesifik Anda.

Mungkin saya tidak mengerti maksudnya karena saya hanya terbiasa bekerja dengan cara yang berbeda, tetapi jika saya tidak tahu cara menggunakan perpustakaan, saya tidak bergantung pada pelengkapan otomatis dan menebak-nebak untuk mengetahui apa yang harus dilakukan.
Sebagai gantinya saya memeriksa dokumentasi perpustakaan dan, jika itu tidak membantu, saya menyelami kode untuk melihat cara kerjanya.

Karenanya mengapa saya pikir dokumentasi yang ditingkatkan (visual atau dalam kode) adalah cara untuk menyelesaikan ini.
Tapi mungkin saya kehilangan sesuatu di sini atau kasus penggunaan tertentu di mana dokumentasi yang lebih baik tidak akan membantu?
Apakah pemahaman saya tentang "dapat ditemukan" benar?

Apakah pemahaman saya tentang "dapat ditemukan" benar?

Tidak dalam kasus saya. Harapan saya adalah dapat melakukan ls Faraday di pry , diikuti oleh $ Faraday.get , dll. jika saya ingin menyelami metode tertentu. Saya merasa dapat melakukan ini secara efektif dengan permata lain yang pernah saya gunakan, jarang (jika pernah) perlu menavigasi ke halaman dokumentasi, karenanya membuka tiket ini. (Ini adalah tambahan untuk masalah lain yang disebutkan di atas, seperti alat analisis statis yang gagal mengenali kode yang menggunakan perpustakaan.)

Sekali lagi terima kasih telah mendengarkan kami.

Saya suka Situs Web Faraday! Mungkin saya bisa mengirimkan PR dengan beberapa saran? Senang membantu. Saya pikir upaya semacam itu selalu membuahkan hasil bagi pendatang baru. Beri tahu saya jika Anda tertarik.

Dalam hal pry + ls Faraday , saya juga penggemar pola itu dan menggunakannya secara ekstensif. Menjauh dari method_missing bukanlah ide yang buruk. Ruby perlahan-lahan ditarik ke arah itu dengan munculnya Ruby 3, server bahasa, RBS, dll. Saya pikir ini sekunder dari dokumen.

@gurgeous Kami docs/ dengan satu set Gemfile (dan README) yang digunakan untuk memublikasikan situs web ke GitHub Pages, yang kami gunakan. Jika penggunaannya tidak jelas, proses pembaruan situs web, silakan buka Masalah atau PR untuk _itu_ juga.

Terima kasih telah peduli dengan pengguna Faraday!

Saya suka Situs Web Faraday! Mungkin saya bisa mengirimkan PR dengan beberapa saran? Senang membantu. Saya pikir upaya semacam itu selalu membuahkan hasil bagi pendatang baru. Beri tahu saya jika Anda tertarik.

@gurgeous benar-benar! Kami selalu menerima bantuan untuk meningkatkan dokumentasi atau situs web, karena hal-hal yang jelas bagi kami pengelola mungkin tidak begitu jelas bagi pengguna. Selain itu, kami benar-benar berjuang dengan waktu dan itu sering kali harus dibayar dengan biaya dokumentasi. Sebenarnya, dokumentasi akan jauh lebih buruk jika bukan karena @olleolleolle upaya yang berkelanjutan !

Pada titik pry (cc @dduugg), saya tidak pernah menggunakannya karena itu mengapa saya mungkin gagal memahaminya.
Saya baru saja mencobanya dengan detail tambahan Anda dan saya perhatikan bahwa ls Faraday::Connection memang menunjukkan metode yang dihasilkan secara dinamis serta yang didelegasikan .
Jadi pemahaman awal saya bahwa kami tidak dapat menggunakan "sihir" Ruby semacam ini salah, dan satu-satunya batasan adalah menggunakan missing_method .

Apa yang saya tidak terlalu suka, adalah pengenalan metode eksplisit seperti berikut:

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

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

# ... and so on ...

Tetapi jika kita dapat memperbaiki penemuan pry dengan menambahkan definisi dinamis atau delegasi ke modul Faraday , maka itu adalah sesuatu yang saya setujui. Maaf karena tidak mendapatkannya pertama kali!

Tidak perlu khawatir dengan keterbatasan waktu. Jangan pernah merasa buruk karena menjadi pengelola open source! Kami menghargai upaya Anda terlepas dari itu. saya juga pernah kesana...

Saya akan memulai diskusi re: docs untuk memastikan kita berada di halaman yang sama.

@iMacTia Bagaimana pengguna tahu untuk melihat ke Faraday::Connection ? Sejak itu saya beralih ke permata HTTP dengan API yang dapat ditemukan, tetapi saya melihat sekilas https://lostisland.github.io/faraday/usage/ dan tidak ada contoh kode yang secara eksplisit menggunakannya (meskipun yang terakhir melakukannya secara implisit). Contoh kebanyakan memanggil metode statis pada Faraday , tetapi mereka tidak ditemukan di pry. Saya tidak tahu ada permata lain yang menggunakan pendekatan ini, dan saya masih menganggapnya sebagai anti-pola.

Terima kasih, seperti biasa, karena telah mendengarkanku.